mirror of https://gerrit.osmocom.org/libosmocore
251 lines
8.0 KiB
Plaintext
251 lines
8.0 KiB
Plaintext
|
|
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.
|
|
|