import oap message parsing / encoding from openbsc.git; AGPL->GPL

In the process, also:
* Change the license from AGPLv3 to GPLv2-or-later;
* correct spelling of 'sysmocom' to lowercase;
* add '2016' to the copyright;
* rename to osmo_*;
* add API docs;
* add logging category DLOAP: define id and add to internal_cat;
* redirect all oap.c logging to DLOAP.

A unit test will follow in a subsequent patch, since it needs a minor tweak for
decoding of boolean values.

The related openbsc change-id is I2f06aaa6eb54eafa860cfed8e72e41d82ff1c4cf.

Tweaked-by: Neels Hofmeyr
Change-Id: If5099e60681a215e798b6675f21813f26769c253

1 files changed, 250 insertions, 0 deletions

diff --git a/doc/osmocom-authn-protocol.txt b/doc/osmocom-authn-protocol.txt
new file mode 100644
index 00000000..1b6794e8
--- /dev/null
+++ b/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.
+