[PATCH 3/8] Add OAP design document.

Sponsored-by: On-Waves ehf --- openbsc/doc/osmocom-authn-protocol.txt | 250 +++++++++++++++++++++++++++++++++ 1 file changed, 250 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..1b6794e --- /dev/null +++ b/openbsc/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. + -- 2.1.4