Sponsored-by: On-Waves ehf
---
openbsc/doc/osmocom-authn-protocol.txt | 191 +++++++++++++++++++++++++++++++++
1 file changed, 191 insertions(+)
create mode 100644 openbsc/doc/osmocom-authn-protocol.txt
diff --git a/openbsc/doc/osmocom-authn-protocol.txt
b/openbsc/doc/osmocom-authn-protocol.txt
new file mode 100644
index 0000000..660fdb6
--- /dev/null
+++ b/openbsc/doc/osmocom-authn-protocol.txt
@@ -0,0 +1,191 @@
+
+ Osmocom Authentication Protocol (OAP)
+
+1. General
+
+This document describes the remote protocol that is used by the SGSN and MAP
+proxy to authenticate each other. The protocol and the messages are designed
+after the corresponding MAP messages (see GSM 09.02) with the following
+differences:
+
+ - The encoding uses TLV structures instead of ASN.1 encodings
+ - Segmentation is not used
+
+See the specification of the Gr interface (GSM 03.60).
+
+1.1. Connection
+
+The protocol expects that a reliable, ordered, packet boundaries preserving
+connection is used (e.g. IPA over TCP). The remote peer is either a service
+that understands the protocol natively or a wrapper service that maps the
+messages to/from real MAP messages that can be used to directly communicate
+with an HLR.
+
+1.2. Using IPA
+
+By default, the following identifiers should be used:
+ - IPA protocol: 0xee (OSMO)
+ - IPA OSMO protocol extension: 0x06
+
+2. Procedures
+
+Ideal communication sequence:
+
+ SGSN MAP
+ | |
+ | Register (Id) |
+ |----------------------------------->|
+ | |
+ | Challenge (RAND+AUTN) |
+ |<-----------------------------------|
+ | |
+ | Challenge Result (SRES) |
+ |----------------------------------->|
+ | |
+ | Register Result |
+ |<-----------------------------------|
+
+2.1. Register
+
+The SGSN sends a REGISTER_REQ message containing an SGSN identifier number.
+
+2.2. Challenge
+
+The OAP server (optionally) sends a CHALLENGE_REQ to the SGSN, containing
+random bytes and a milenage authentication token generated from these random
+bytes, using a shared secret, to authenticate itself to the OAP client (SGSN).
+The server may omit this challenge entirely, based on its configuration, and
+immediately reply with a Register Result response. If the SGSN cannot be
+registered (e.g. id is invalid), the server sends a REGISTER_ERR response.
+
+2.3. Challenge Result
+
+When the SGSN has received a Challenge, it may verify the server's
+authenticity, and reply with a CHALLENGE_RES message. This shall contain SRES
+(and Kc?) authentication tokens generated by milenage from the same random
+bytes received from the server and the same shared secet. If the SGSN cannot
+verify the server's authenticity, it shall instead send a CHALLENGE_ERR
+message.
+
+2.4. Register Result
+
+The MAP sends a REGISTER_RES message to indicate that registration has been
+successful. If the MAP proxy cannot register the SGSN (e.g. invalid challenge
+response), it sends 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
+
+SGSN -> Network peer
+
+ IEI Info Element Type Pres. Format Length
+ Message type 4.2.1 M V 1
+ 30 SGSN Id big endian int (2 oct) M TLV 4
+
+3.2.2. Register Error
+
+Network peer -> SGSN
+
+ 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
+
+Network peer -> SGSN
+
+ IEI Info Element Type Pres. Format Length
+ Message type 4.2.1 M V 1
+
+3.2.3. Challenge
+
+Network peer -> SGSN
+
+ 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
+
+SGSN -> Network peer
+
+ 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
+
+SGSN -> Network peer
+
+ IEI Info Element Type Pres. Format Length
+ Message type 4.2.1 M V 1
+ 21 SRES octet string (4) M TLV 6
+ 22 Kc octet string (8) M TLV 10
+
+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 |
+ | |
+ +---------------------------------------------------+
+
+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 |
+ | 0x21 SRES octet string |
+ | 0x22 Kc octet string |
+ | 0x23 AUTN octet string |
+ | 0x30 SGSN Id big endian int (2 octets) |
+ +---------------------------------------------------------+
+
+4.2.3. SGSN Id
+
+ 8 7 6 5 4 3 2 1
+ +-----------------------------------------------------+
+ | | SGSN Id IEI | octet 1
+ +-----------------------------------------------------+
+ | Length of SGSN Id IE contents (2) | octet 2
+ +-----------------------------------------------------+
+ | SGSN Id number, most significant byte | octet 3
+ +-----------------------------------------------------+
+ | SGSN Id number, least significant byte | octet 4
+ +-----------------------------------------------------+
+
+The SGSN Id number shall be interpreted as an unsigned 16bit integer, where 0
+indicates an invalid / unset Id.
+
+
--
2.1.4