OAP:remove design doc. osmocom-authn-protocol.txt

Osmocom Authentication Protocol design document
 is removed from libosmocore project as this
 information has been included in the User Manual.
 It is present in SGSN User Manual.

 relates to OS#1874

Change-Id: I2d4dc608622a7484e67b15f930efc76e28285045
This commit is contained in:
ikostov 2017-02-15 17:55:36 +01:00
parent 437ed4ab42
commit 3e6d5701e6
2 changed files with 1 additions and 251 deletions

View File

@ -13,7 +13,7 @@ $(top_srcdir)/.version:
dist-hook: dist-hook:
echo $(VERSION) > $(distdir)/.tarball-version 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 if HAVE_DOXYGEN

View File

@ -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.