summaryrefslogtreecommitdiffstats
path: root/doc/osmocom-authn-protocol.txt
blob: 6d057bea90efbb029b182c1ebbea498ad64ff038 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
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.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 (16)	M	TLV	18

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.