== Osmocom Authentication Protocol (OAP)

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

=== Connection

The protocol expects that a reliable, ordered, packet boundaries
preserving connection is used (e.g. IPA over TCP).

=== Using IPA

By default, the following identifiers should be used:
  - IPA protocol: 0xee (OSMO)
  - IPA OSMO protocol extension: 0x06 (OAP)

=== Procedures

.Ideal communication sequence
[mscgen]
----
msc {
	cli [label="Client"], srv [label="Server"];

	cli => srv [label="Register (ID)"];
	cli <= srv [label="Challenge (RAND+AUTN)"];
	cli => srv [label="Challenge Result (XRES)"];
	cli <= srv [label="Register Result"];
}
----

.Variation "test setup"
[mscgen]
----
msc {
	cli [label="Client"], srv [label="Server"];

	cli => srv [label="Register (ID)"];
	cli <= srv [label="Register Result"];
}
----

.Variation "invalid sequence nr":
[mscgen]
----
msc {
	cli [label="Client"], srv [label="Server"];

	cli => srv [label="Register (ID)"];
	cli <= srv [label="Challenge (RAND+AUTN)"];
	cli => srv [label="Sync Request (AUTS)"];
	cli <= srv [label="Challenge (RAND+AUTN')"];
	cli => srv [label="Challenge Result (XRES)"];
	cli <= srv [label="Register Result"];
}
----

==== Register

The client sends a REGISTER_REQ message containing an identifier number.

[[oap-challenge]]
==== 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.

==== 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 secret. 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.

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

==== Sync Result

If the server has received a valid Sync Request, it shall answer by directly
sending another Challenge (see <<oap-challenge>>). If an invalid Sync
Request is received, the server shall reply with a REGISTER_ERR message.

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

=== Message Format

Every message is based on the following message format

[options="header",cols="5%,20%,45%,10%,10%,10%"]
|===
|IEI|IE|Type|Presence|Format|Length
|  |Message Type|<<common-oap-ie-msgtype>>|M|V|1
|===

The receiver shall be able to receive IEs in any order. Unknown IEs shall be
ignored.

==== Register Request

Direction: Client -> Server

[options="header",cols="5%,20%,45%,10%,10%,10%"]
|===
|IEI|IE|Type|Presence|Format|Length
|  |Message Type|<<common-oap-ie-msgtype>>|M|V|1
|30|Client ID|<<common-oap-ie-clientid>>|M|TLV|4
|===

==== Register Error

Direction: Server -> Client

[options="header",cols="5%,20%,45%,10%,10%,10%"]
|===
|IEI|IE|Type|Presence|Format|Length
|  |Message Type|<<common-oap-ie-msgtype>>|M|V|1
|02|Cause|GMM Cause, TS 24.008: 10.5.5.14|M|TLV|3
|===

==== Register Result

Direction: Server -> Client

[options="header",cols="5%,20%,45%,10%,10%,10%"]
|===
|IEI|IE|Type|Presence|Format|Length
|  |Message Type|<<common-oap-ie-msgtype>>|M|V|1
|===

==== Challenge

Direction: Server -> Client

[options="header",cols="5%,20%,45%,10%,10%,10%"]
|===
|IEI|IE|Type|Presence|Format|Length
|  |Message Type|<<common-oap-ie-msgtype>>|M|V|1
|20|RAND|octet string (16)|TLV|18
|23|AUTN|octet string (16)|TLV|18
|===

==== Challenge Error

Direction: Client -> Server

[options="header",cols="5%,20%,45%,10%,10%,10%"]
|===
|IEI|IE|Type|Presence|Format|Length
|  |Message Type|<<common-oap-ie-msgtype>>|M|V|1
|02|Cause|GMM Cause, TS 24.008: 10.5.5.14|M|TLV|3
|===

==== Challenge Result

Direction: Client -> Server

[options="header",cols="5%,20%,45%,10%,10%,10%"]
|===
|IEI|IE|Type|Presence|Format|Length
|  |Message Type|<<common-oap-ie-msgtype>>|M|V|1
|21|XRES|octet string (8)|TLV|10
|===

==== Sync Request

Direction: Client -> Server

[options="header",cols="5%,20%,45%,10%,10%,10%"]
|===
|IEI|IE|Type|Presence|Format|Length
|  |Message Type|<<common-oap-ie-msgtype>>|M|V|1
|20|AUTS|octet string (14)|TLV|16
|===

==== Sync Error

Not used.

==== Sync Result

Not used.

=== Information Elements

[[common-oap-ie-msgtype]]
==== Message Type

[options="header",cols="15%,85%"]
|===
|0x04|Register Request
|0x05|Register Error
|0x06|Register Result
|0x08|Challenge Request
|0x09|Challenge Error
|0x0a|Challenge Result
|0x0c|Sync Request
|0x0d|Sync Error (not used)
|0x0e|Sync Result (not used)
|===

[[common-oap-iei]]
==== IE Identifier (informational)

These are the standard values for the IEI.

[options="header",cols="15%,15%,70%"]
|===
|IEI|Info Element|Type
|0x02|Cause|GMM Cause, 04.08: 10.5.5.14
|0x20|RAND|Octet String
|0x23|AUTN|Octet Strong
|0x24|XRES|Octet String
|0x25|AUTS|Octet String
|0x30|Client ID|big endian integer, 16 bit
|===

[[common-oap-ie-clientid]]
==== Client ID

[packetdiag]
----
{
	colwidth = 32
	node_height = 24

	0-7:	Client ID IEI
	8-15:	Length (2)
	16-31:	Client ID (big endian)
}
----

The Client ID number shall be interpreted as an unsigned 16bit integer, where 0
indicates an invalid / unset ID.