[PATCH] libosmocore[master]: import oap message parsing / encoding from openbsc.git

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

Neels Hofmeyr gerrit-no-reply at lists.osmocom.org
Thu Dec 8 15:37:21 UTC 2016


Review at  https://gerrit.osmocom.org/1375

import oap message parsing / encoding from openbsc.git

In the process, rename to osmo_* and add API docs, update the copyright. Remove
the copyright notice from the .h file as typical in all osmocom headers.

Change-Id: If5099e60681a215e798b6675f21813f26769c253
---
M Makefile.am
A doc/osmocom-authn-protocol.txt
M include/Makefile.am
M include/osmocom/core/logging.h
A include/osmocom/gsm/oap.h
M src/gsm/Makefile.am
M src/gsm/libosmogsm.map
A src/gsm/oap.c
8 files changed, 492 insertions(+), 3 deletions(-)


  git pull ssh://gerrit.osmocom.org:29418/libosmocore refs/changes/75/1375/1

diff --git a/Makefile.am b/Makefile.am
index 185127e..9c901ea 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -13,7 +13,7 @@
 dist-hook:
 	echo $(VERSION) > $(distdir)/.tarball-version
 
-EXTRA_DIST = git-version-gen .version
+EXTRA_DIST = git-version-gen .version doc/osmocom-authn-protocol.txt
 
 if HAVE_DOXYGEN
 
diff --git a/doc/osmocom-authn-protocol.txt b/doc/osmocom-authn-protocol.txt
new file mode 100644
index 0000000..1b6794e
--- /dev/null
+++ b/doc/osmocom-authn-protocol.txt
@@ -0,0 +1,250 @@
+
+               Osmocom Authentication Protocol (OAP)
+
+1. General
+
+The Osmocom Authentication Protocol employs mutual authentication to register a
+client with a server over an IPA connection. Milenage is used as the
+authentication algorithm, where client and server have a shared secret.
+
+For example, an SGSN, as OAP client, may use its SGSN ID to register with a MAP
+proxy, an OAP server.
+
+1.1. Connection
+
+The protocol expects that a reliable, ordered, packet boundaries preserving
+connection is used (e.g. IPA over TCP).
+
+1.2. Using IPA
+
+By default, the following identifiers should be used:
+  - IPA protocol: 0xee (OSMO)
+  - IPA OSMO protocol extension: 0x06 (OAP)
+
+2. Procedures
+
+Ideal communication sequence:
+
+   Client                               Server
+     |                                    |
+     |  Register (ID)                     |
+     |----------------------------------->|
+     |                                    |
+     |  Challenge (RAND+AUTN)             |
+     |<-----------------------------------|
+     |                                    |
+     |  Challenge Result (XRES)           |
+     |----------------------------------->|
+     |                                    |
+     |  Register Result                   |
+     |<-----------------------------------|
+
+Variation "test setup":
+
+   Client                               Server
+     |                                    |
+     |  Register (ID)                     |
+     |----------------------------------->|
+     |                                    |
+     |  Register Result                   |
+     |<-----------------------------------|
+
+Variation "invalid sequence nr":
+
+   Client                               Server
+     |                                    |
+     |  Register (ID)                     |
+     |----------------------------------->|
+     |                                    |
+     |  Challenge (RAND+AUTN)             |
+     |<-----------------------------------|
+     |                                    |
+     |  Sync Request (AUTS)               |
+     |----------------------------------->|
+     |                                    |
+     |  Challenge (RAND'+AUTN')           |
+     |<-----------------------------------|
+     |                                    |
+     |  Challenge Result (XRES)           |
+     |----------------------------------->|
+     |                                    |
+     |  Register Result                   |
+     |<-----------------------------------|
+
+2.1. Register
+
+The client sends a REGISTER_REQ message containing an identifier number.
+
+2.2. Challenge
+
+The OAP server (optionally) sends back a CHALLENGE_REQ, containing random bytes
+and a milenage authentication token generated from these random bytes, using a
+shared secret, to authenticate itself to the OAP client. The server may omit
+this challenge entirely, based on its configuration, and immediately reply with
+a Register Result response. If the client cannot be registered (e.g. id is
+invalid), the server sends a REGISTER_ERR response.
+
+2.3. Challenge Result
+
+When the client has received a Challenge, it may verify the server's
+authenticity and validity of the sequence number (included in AUTN), and, if
+valid, reply with a CHALLENGE_RES message. This shall contain an XRES
+authentication token generated by milenage from the same random bytes received
+from the server and the same shared secet. If the client decides to cancel the
+registration (e.g. invalid AUTN), it shall not reply to the CHALLENGE_REQ; a
+CHALLENGE_ERR message may be sent, but is not mandatory. For example, the
+client may directly start with a new REGISTER_REQ message.
+
+2.4. Sync Request
+
+When the client has received a Challenge but sees an invalid sequence number
+(embedded in AUTN, according to the milenage algorithm), the client may send a
+SYNC_REQ message containing an AUTS synchronisation token.
+
+2.5. Sync Result
+
+If the server has received a valid Sync Request, it shall answer by directly
+sending another Challenge (see 2.2.). If an invalid Sync Request is received,
+the server shall reply with a REGISTER_ERR message.
+
+2.6. Register Result
+
+The server sends a REGISTER_RES message to indicate that registration has been
+successful. If the server cannot register the client (e.g. invalid challenge
+response), it shall send a REGISTER_ERR message.
+
+3. Message Format
+
+3.1. General
+
+Every message is based on the following message format
+
+  IEI	Info Element		Type			Pres.	Format	Length
+	Message type		4.2.1			M	V	1
+
+The receiver shall be able to receive IEs in any order. Unknown IEs shall be
+ignored.
+
+3.2.1. Register Request
+
+Client -> Server
+
+  IEI	Info Element		Type			Pres.	Format	Length
+	Message type		4.2.1			M	V	1
+  30	Client ID		big endian int (2 oct)	M	TLV	4
+
+3.2.2. Register Error
+
+Server -> Client
+
+  IEI	Info Element		Type			Pres.	Format	Length
+	Message type		4.2.1			M	V	1
+  02	Cause			GMM cause,		M	TLV	3
+				04.08: 10.5.5.14
+
+3.2.6. Register Result
+
+Server -> Client
+
+  IEI	Info Element		Type			Pres.	Format	Length
+	Message type		4.2.1			M	V	1
+
+3.2.3. Challenge
+
+Server -> Client
+
+  IEI	Info Element		Type			Pres.	Format	Length
+	Message type		4.2.1			M	V	1
+  20	RAND			octet string (16)	M	TLV	18
+  23	AUTN			octet string (16)	M	TLV	18
+
+3.2.4. Challenge Error
+
+Client -> Server
+
+  IEI	Info Element		Type			Pres.	Format	Length
+	Message type		4.2.1			M	V	1
+  02	Cause			GMM cause,		M	TLV	3
+				04.08: 10.5.5.14
+
+3.2.5. Challenge Result
+
+Client -> Server
+
+  IEI	Info Element		Type			Pres.	Format	Length
+	Message type		4.2.1			M	V	1
+  21	XRES			octet string (8)	M	TLV	10
+
+3.2.3. Sync Request
+
+Client -> Server
+
+  IEI	Info Element		Type			Pres.	Format	Length
+	Message type		4.2.1			M	V	1
+  20	AUTS			octet string (16)	M	TLV	18
+
+3.2.4. Sync Error
+
+Server -> Client
+
+  IEI	Info Element		Type			Pres.	Format	Length
+	Message type		4.2.1			M	V	1
+  02	Cause			GMM cause,		M	TLV	3
+				04.08: 10.5.5.14
+
+4. Information Elements
+
+4.1. General
+
+[...]
+
+4.2.1. Message Type
+
+  +---------------------------------------------------+
+  | 8 7 6 5 4 3 2 1                                   |
+  |                                                   |
+  | 0 0 0 0 0 1 0 0  - Register Request               |
+  | 0 0 0 0 0 1 0 1  - Register Error                 |
+  | 0 0 0 0 0 1 1 0  - Register Result                |
+  |                                                   |
+  | 0 0 0 0 1 0 0 0  - Challenge Request              |
+  | 0 0 0 0 1 0 0 1  - Challenge Error                |
+  | 0 0 0 0 1 0 1 0  - Challenge Result               |
+  |                                                   |
+  | 0 0 0 0 1 1 0 0  - Sync Request                   |
+  | 0 0 0 0 1 1 0 1  - Sync Error (not used)          |
+  | 0 0 0 0 1 1 1 0  - Sync Result (not used)         |
+  |                                                   |
+  +---------------------------------------------------+
+
+4.2.2. IE Identifier (informational)
+
+These are the standard values for the IEI.
+
+  +---------------------------------------------------------+
+  | IEI    Info Element   Type                              |
+  |                                                         |
+  | 0x02   Cause          GMM cause, 04.08: 10.5.5.14       |
+  | 0x20   RAND           octet string                      |
+  | 0x23   AUTN           octet string                      |
+  | 0x24   XRES           octet string                      |
+  | 0x25   AUTS           octet string                      |
+  | 0x30   Client ID      big endian int (2 octets)         |
+  +---------------------------------------------------------+
+
+4.2.3. Client ID
+
+     8      7      6      5      4      3      2      1
+  +-----------------------------------------------------+
+  |     |  Client ID IEI                                | octet 1
+  +-----------------------------------------------------+
+  |   Length of Client ID IE contents (2)               | octet 2
+  +-----------------------------------------------------+
+  |   Client ID number, most significant byte           | octet 3
+  +-----------------------------------------------------+
+  |   Client ID number, least significant byte          | octet 4
+  +-----------------------------------------------------+
+
+The Client ID number shall be interpreted as an unsigned 16bit integer, where 0
+indicates an invalid / unset ID.
+
diff --git a/include/Makefile.am b/include/Makefile.am
index c125691..0a300a8 100644
--- a/include/Makefile.am
+++ b/include/Makefile.am
@@ -82,6 +82,7 @@
                        osmocom/gsm/mncc.h \
                        osmocom/gsm/prim.h \
                        osmocom/gsm/l1sap.h \
+                       osmocom/gsm/oap.h \
                        osmocom/gsm/protocol/gsm_03_40.h \
                        osmocom/gsm/protocol/gsm_03_41.h \
                        osmocom/gsm/protocol/gsm_04_08.h \
diff --git a/include/osmocom/core/logging.h b/include/osmocom/core/logging.h
index 581ebce..f9c58bb 100644
--- a/include/osmocom/core/logging.h
+++ b/include/osmocom/core/logging.h
@@ -92,7 +92,8 @@
 #define DLGTP		-9	/*!< GTP (GPRS Tunneling Protocol */
 #define DLSTATS		-10	/*!< Statistics */
 #define DLGSUP		11	/*!< Generic Subscriber Update Protocol */
-#define OSMO_NUM_DLIB	11	/*!< Number of logging sub-systems in libraries */
+#define DLOAP		12	/*!< Osmocom Authentication Protocol */
+#define OSMO_NUM_DLIB	12	/*!< Number of logging sub-systems in libraries */
 
 /*! Configuration of singgle log category / sub-system */
 struct log_category {
diff --git a/include/osmocom/gsm/oap.h b/include/osmocom/gsm/oap.h
new file mode 100644
index 0000000..fa3ef16
--- /dev/null
+++ b/include/osmocom/gsm/oap.h
@@ -0,0 +1,50 @@
+#pragma once
+
+#include <stdint.h>
+#include <osmocom/core/msgb.h>
+#include <osmocom/gsm/protocol/gsm_04_08_gprs.h>
+
+/*! \brief Information Element Identifiers for OAP IEs.
+ * They match osmo_gsup_iei (so far). */
+enum osmo_oap_iei {
+	OAP_CAUSE_IE			= 0x02,
+	OAP_RAND_IE			= 0x20,
+	OAP_AUTN_IE			= 0x23,
+	OAP_XRES_IE			= 0x24,
+	OAP_AUTS_IE			= 0x25,
+	OAP_CLIENT_ID_IE		= 0x30,
+};
+
+/*! \brief OAP message types */
+enum osmo_oap_message_type {
+	OAP_MSGT_REGISTER_REQUEST	= 0b00000100,
+	OAP_MSGT_REGISTER_ERROR		= 0b00000101,
+	OAP_MSGT_REGISTER_RESULT	= 0b00000110,
+
+	OAP_MSGT_CHALLENGE_REQUEST	= 0b00001000,
+	OAP_MSGT_CHALLENGE_ERROR	= 0b00001001,
+	OAP_MSGT_CHALLENGE_RESULT	= 0b00001010,
+
+	OAP_MSGT_SYNC_REQUEST		= 0b00001100,
+	OAP_MSGT_SYNC_ERROR		= 0b00001101,
+	OAP_MSGT_SYNC_RESULT		= 0b00001110,
+};
+
+/*! \brief Parsed/decoded OAP protocol message */
+struct osmo_oap_message {
+	enum osmo_oap_message_type message_type;
+	enum gsm48_gmm_cause cause;
+	uint16_t client_id;
+	int rand_present;
+	uint8_t rand[16];
+	int autn_present;
+	uint8_t autn[16];
+	int xres_present;
+	uint8_t xres[8];
+	int auts_present;
+	uint8_t auts[16];
+};
+
+int osmo_oap_decode(struct osmo_oap_message *oap_msg, const uint8_t *data,
+		    size_t data_len);
+void osmo_oap_encode(struct msgb *msg, const struct osmo_oap_message *oap_msg);
diff --git a/src/gsm/Makefile.am b/src/gsm/Makefile.am
index 3877f78..4ea55e1 100644
--- a/src/gsm/Makefile.am
+++ b/src/gsm/Makefile.am
@@ -22,7 +22,7 @@
 			auth_milenage.c milenage/aes-encblock.c gea.c \
 			milenage/aes-internal.c milenage/aes-internal-enc.c \
 			milenage/milenage.c gan.c ipa.c gsm0341.c apn.c \
-			gsup.c gprs_gea.c gsm0503_conv.c
+			gsup.c gprs_gea.c gsm0503_conv.c oap.c
 libgsmint_la_LDFLAGS = -no-undefined
 libgsmint_la_LIBADD = $(top_builddir)/src/libosmocore.la
 
diff --git a/src/gsm/libosmogsm.map b/src/gsm/libosmogsm.map
index 3e7333c..a3d224f 100644
--- a/src/gsm/libosmogsm.map
+++ b/src/gsm/libosmogsm.map
@@ -356,5 +356,8 @@
 osmo_gsup_encode;
 osmo_gsup_decode;
 
+osmo_oap_encode;
+osmo_oap_decode;
+
 local: *;
 };
diff --git a/src/gsm/oap.c b/src/gsm/oap.c
new file mode 100644
index 0000000..979bde6
--- /dev/null
+++ b/src/gsm/oap.c
@@ -0,0 +1,184 @@
+/* Osmocom Authentication Protocol message encoder/decoder */
+
+/* (C) 2015-2016 by sysmocom s.f.m.c. GmbH
+ * All Rights Reserved
+ *
+ * Author: Neels Hofmeyr
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+#include <osmocom/core/utils.h>
+#include <osmocom/core/logging.h>
+#include <osmocom/core/msgb.h>
+#include <osmocom/gsm/tlv.h>
+#include <osmocom/gsm/oap.h>
+
+#include <stdint.h>
+
+/*! \brief Decode OAP message data.
+ * \param[out] oap_msg  Parsed data is written to this instance.
+ * \param[in] data  Pointer to the data buffer containing the OAP message.
+ * \param[in] data_len  Length of the OAP message data.
+ * \returns 0 on success, a negative cause value on failure.
+ */
+int osmo_oap_decode(struct osmo_oap_message *oap_msg,
+		    const uint8_t *const_data, size_t data_len)
+{
+	int rc;
+	uint8_t tag;
+	/* the shift/match functions expect non-const pointers, but we'll
+	 * either copy the data or cast pointers back to const before returning
+	 * them
+	 */
+	uint8_t *data = (uint8_t *)const_data;
+	uint8_t *value;
+	size_t value_len;
+
+	memset(oap_msg, 0, sizeof(*oap_msg));
+
+	/* message type */
+	rc = osmo_shift_v_fixed(&data, &data_len, 1, &value);
+	if (rc < 0)
+		return -GMM_CAUSE_INV_MAND_INFO;
+	oap_msg->message_type = osmo_decode_big_endian(value, 1);
+
+	/* specific parts */
+	while (data_len > 0) {
+		enum osmo_oap_iei iei;
+
+		rc = osmo_shift_tlv(&data, &data_len, &tag, &value, &value_len);
+		if (rc < 0)
+			return -GMM_CAUSE_PROTO_ERR_UNSPEC;
+
+		iei = tag;
+
+		switch (iei) {
+		case OAP_CLIENT_ID_IE:
+			if (value_len != 2) {
+				LOGP(DLOAP, LOGL_NOTICE,
+				     "OAP IE type client ID (%d) should be 2 octets, but has %d\n",
+				     (int)iei, (int)value_len);
+				return -GMM_CAUSE_PROTO_ERR_UNSPEC;
+			}
+
+			oap_msg->client_id = osmo_decode_big_endian(value, value_len);
+
+			if (oap_msg->client_id == 0) {
+				LOGP(DLOAP, LOGL_NOTICE,
+				     "OAP IE type client ID (%d): client ID must be nonzero.\n",
+				     (int)iei);
+				return -GMM_CAUSE_PROTO_ERR_UNSPEC;
+			}
+			break;
+
+		case OAP_AUTN_IE:
+			if (value_len != sizeof(oap_msg->autn)) {
+				LOGP(DLOAP, LOGL_NOTICE,
+				     "OAP IE type AUTN (%d) should be %d octets, but has %d\n",
+				     (int)iei, (int)sizeof(oap_msg->autn), (int)value_len);
+				return -GMM_CAUSE_PROTO_ERR_UNSPEC;
+			}
+			memcpy(oap_msg->autn, value, value_len);
+			oap_msg->autn_present = value_len;
+			break;
+
+		case OAP_RAND_IE:
+			if (value_len != sizeof(oap_msg->rand)) {
+				LOGP(DLOAP, LOGL_NOTICE,
+				     "OAP IE type RAND (%d) should be %d octets, but has %d\n",
+				     (int)iei, (int)sizeof(oap_msg->rand), (int)value_len);
+				return -GMM_CAUSE_PROTO_ERR_UNSPEC;
+			}
+			memcpy(oap_msg->rand, value, value_len);
+			oap_msg->rand_present = value_len;
+			break;
+
+		case OAP_XRES_IE:
+			if (value_len != sizeof(oap_msg->xres)) {
+				LOGP(DLOAP, LOGL_NOTICE,
+				     "OAP IE type XRES (%d) should be %d octets, but has %d\n",
+				     (int)iei, (int)sizeof(oap_msg->xres), (int)value_len);
+				return -GMM_CAUSE_PROTO_ERR_UNSPEC;
+			}
+			memcpy(oap_msg->xres, value, value_len);
+			oap_msg->xres_present = value_len;
+			break;
+
+		case OAP_AUTS_IE:
+			if (value_len != sizeof(oap_msg->auts)) {
+				LOGP(DLOAP, LOGL_NOTICE,
+				     "OAP IE type AUTS (%d) should be %d octets, but has %d\n",
+				     (int)iei, (int)sizeof(oap_msg->auts), (int)value_len);
+				return -GMM_CAUSE_PROTO_ERR_UNSPEC;
+			}
+			memcpy(oap_msg->auts, value, value_len);
+			oap_msg->auts_present = value_len;
+			break;
+
+		case OAP_CAUSE_IE:
+			if (value_len > 1) {
+				LOGP(DLOAP, LOGL_ERROR,
+				     "OAP cause may not exceed one octet, is %d", (int)value_len);
+				return -GMM_CAUSE_PROTO_ERR_UNSPEC;
+			}
+			oap_msg->cause = *value;
+			break;
+
+		default:
+			LOGP(DLOAP, LOGL_NOTICE,
+			     "OAP IE type %d unknown\n", iei);
+			continue;
+		}
+	}
+
+	return 0;
+}
+
+/*! \brief Compose OAP message data.
+ * \param[out] msg  OAP message data is appended to this message buffer.
+ * \param[in] oap_msg  Elements to encode in the message data.
+ */
+void osmo_oap_encode(struct msgb *msg, const struct osmo_oap_message *oap_msg)
+{
+	uint8_t u8;
+
+	/* generic part */
+	OSMO_ASSERT(oap_msg->message_type);
+	msgb_v_put(msg, (uint8_t)oap_msg->message_type);
+
+	/* specific parts */
+	if ((u8 = oap_msg->cause))
+		msgb_tlv_put(msg, OAP_CAUSE_IE, sizeof(u8), &u8);
+
+	if (oap_msg->client_id > 0)
+		msgb_tlv_put(msg, OAP_CLIENT_ID_IE, sizeof(oap_msg->client_id),
+			     osmo_encode_big_endian(oap_msg->client_id,
+						    sizeof(oap_msg->client_id)));
+
+	if (oap_msg->rand_present)
+		msgb_tlv_put(msg, OAP_RAND_IE, sizeof(oap_msg->rand), oap_msg->rand);
+
+	if (oap_msg->autn_present)
+		msgb_tlv_put(msg, OAP_AUTN_IE, sizeof(oap_msg->autn), oap_msg->autn);
+
+	if (oap_msg->auts_present)
+		msgb_tlv_put(msg, OAP_AUTS_IE, sizeof(oap_msg->auts), oap_msg->auts);
+
+	if (oap_msg->xres_present)
+		msgb_tlv_put(msg, OAP_XRES_IE, sizeof(oap_msg->xres), oap_msg->xres);
+
+	msg->l2h = msg->data;
+}

-- 
To view, visit https://gerrit.osmocom.org/1375
To unsubscribe, visit https://gerrit.osmocom.org/settings

Gerrit-MessageType: newchange
Gerrit-Change-Id: If5099e60681a215e798b6675f21813f26769c253
Gerrit-PatchSet: 1
Gerrit-Project: libosmocore
Gerrit-Branch: master
Gerrit-Owner: Neels Hofmeyr <nhofmeyr at sysmocom.de>



More information about the gerrit-log mailing list