diff --git a/Makefile.am b/Makefile.am index 9c901ea5a..185127e30 100644 --- a/Makefile.am +++ b/Makefile.am @@ -13,7 +13,7 @@ $(top_srcdir)/.version: dist-hook: echo $(VERSION) > $(distdir)/.tarball-version -EXTRA_DIST = git-version-gen .version doc/osmocom-authn-protocol.txt +EXTRA_DIST = git-version-gen .version if HAVE_DOXYGEN diff --git a/doc/osmocom-authn-protocol.txt b/doc/osmocom-authn-protocol.txt deleted file mode 100644 index ad4fba0fd..000000000 --- a/doc/osmocom-authn-protocol.txt +++ /dev/null @@ -1,250 +0,0 @@ - - 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.3. Register Result - -Server -> Client - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - -3.2.4. 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.5. 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.6. 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.7. Sync Request - -Client -> Server - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 20 AUTS octet string (14) M TLV 16 - -3.2.8. Sync Error - -Not used. - -3.2.9. Sync Result - -Not used. - - -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. -