| Harald Welte | c0f0007 | 2016-04-27 18:32:35 +0200 | [diff] [blame^] | 1 | |
| 2 | Osmocom Authentication Protocol (OAP) |
| 3 | |
| 4 | 1. General |
| 5 | |
| 6 | The Osmocom Authentication Protocol employs mutual authentication to register a |
| 7 | client with a server over an IPA connection. Milenage is used as the |
| 8 | authentication algorithm, where client and server have a shared secret. |
| 9 | |
| 10 | For example, an SGSN, as OAP client, may use its SGSN ID to register with a MAP |
| 11 | proxy, an OAP server. |
| 12 | |
| 13 | 1.1. Connection |
| 14 | |
| 15 | The protocol expects that a reliable, ordered, packet boundaries preserving |
| 16 | connection is used (e.g. IPA over TCP). |
| 17 | |
| 18 | 1.2. Using IPA |
| 19 | |
| 20 | By default, the following identifiers should be used: |
| 21 | - IPA protocol: 0xee (OSMO) |
| 22 | - IPA OSMO protocol extension: 0x06 (OAP) |
| 23 | |
| 24 | 2. Procedures |
| 25 | |
| 26 | Ideal communication sequence: |
| 27 | |
| 28 | Client Server |
| 29 | | | |
| 30 | | Register (ID) | |
| 31 | |----------------------------------->| |
| 32 | | | |
| 33 | | Challenge (RAND+AUTN) | |
| 34 | |<-----------------------------------| |
| 35 | | | |
| 36 | | Challenge Result (XRES) | |
| 37 | |----------------------------------->| |
| 38 | | | |
| 39 | | Register Result | |
| 40 | |<-----------------------------------| |
| 41 | |
| 42 | Variation "test setup": |
| 43 | |
| 44 | Client Server |
| 45 | | | |
| 46 | | Register (ID) | |
| 47 | |----------------------------------->| |
| 48 | | | |
| 49 | | Register Result | |
| 50 | |<-----------------------------------| |
| 51 | |
| 52 | Variation "invalid sequence nr": |
| 53 | |
| 54 | Client Server |
| 55 | | | |
| 56 | | Register (ID) | |
| 57 | |----------------------------------->| |
| 58 | | | |
| 59 | | Challenge (RAND+AUTN) | |
| 60 | |<-----------------------------------| |
| 61 | | | |
| 62 | | Sync Request (AUTS) | |
| 63 | |----------------------------------->| |
| 64 | | | |
| 65 | | Challenge (RAND'+AUTN') | |
| 66 | |<-----------------------------------| |
| 67 | | | |
| 68 | | Challenge Result (XRES) | |
| 69 | |----------------------------------->| |
| 70 | | | |
| 71 | | Register Result | |
| 72 | |<-----------------------------------| |
| 73 | |
| 74 | 2.1. Register |
| 75 | |
| 76 | The client sends a REGISTER_REQ message containing an identifier number. |
| 77 | |
| 78 | 2.2. Challenge |
| 79 | |
| 80 | The OAP server (optionally) sends back a CHALLENGE_REQ, containing random bytes |
| 81 | and a milenage authentication token generated from these random bytes, using a |
| 82 | shared secret, to authenticate itself to the OAP client. The server may omit |
| 83 | this challenge entirely, based on its configuration, and immediately reply with |
| 84 | a Register Result response. If the client cannot be registered (e.g. id is |
| 85 | invalid), the server sends a REGISTER_ERR response. |
| 86 | |
| 87 | 2.3. Challenge Result |
| 88 | |
| 89 | When the client has received a Challenge, it may verify the server's |
| 90 | authenticity and validity of the sequence number (included in AUTN), and, if |
| 91 | valid, reply with a CHALLENGE_RES message. This shall contain an XRES |
| 92 | authentication token generated by milenage from the same random bytes received |
| 93 | from the server and the same shared secet. If the client decides to cancel the |
| 94 | registration (e.g. invalid AUTN), it shall not reply to the CHALLENGE_REQ; a |
| 95 | CHALLENGE_ERR message may be sent, but is not mandatory. For example, the |
| 96 | client may directly start with a new REGISTER_REQ message. |
| 97 | |
| 98 | 2.4. Sync Request |
| 99 | |
| 100 | When the client has received a Challenge but sees an invalid sequence number |
| 101 | (embedded in AUTN, according to the milenage algorithm), the client may send a |
| 102 | SYNC_REQ message containing an AUTS synchronisation token. |
| 103 | |
| 104 | 2.5. Sync Result |
| 105 | |
| 106 | If the server has received a valid Sync Request, it shall answer by directly |
| 107 | sending another Challenge (see 2.2.). If an invalid Sync Request is received, |
| 108 | the server shall reply with a REGISTER_ERR message. |
| 109 | |
| 110 | 2.6. Register Result |
| 111 | |
| 112 | The server sends a REGISTER_RES message to indicate that registration has been |
| 113 | successful. If the server cannot register the client (e.g. invalid challenge |
| 114 | response), it shall send a REGISTER_ERR message. |
| 115 | |
| 116 | 3. Message Format |
| 117 | |
| 118 | 3.1. General |
| 119 | |
| 120 | Every message is based on the following message format |
| 121 | |
| 122 | IEI Info Element Type Pres. Format Length |
| 123 | Message type 4.2.1 M V 1 |
| 124 | |
| 125 | The receiver shall be able to receive IEs in any order. Unknown IEs shall be |
| 126 | ignored. |
| 127 | |
| 128 | 3.2.1. Register Request |
| 129 | |
| 130 | Client -> Server |
| 131 | |
| 132 | IEI Info Element Type Pres. Format Length |
| 133 | Message type 4.2.1 M V 1 |
| 134 | 30 Client ID big endian int (2 oct) M TLV 4 |
| 135 | |
| 136 | 3.2.2. Register Error |
| 137 | |
| 138 | Server -> Client |
| 139 | |
| 140 | IEI Info Element Type Pres. Format Length |
| 141 | Message type 4.2.1 M V 1 |
| 142 | 02 Cause GMM cause, M TLV 3 |
| 143 | 04.08: 10.5.5.14 |
| 144 | |
| 145 | 3.2.6. Register Result |
| 146 | |
| 147 | Server -> Client |
| 148 | |
| 149 | IEI Info Element Type Pres. Format Length |
| 150 | Message type 4.2.1 M V 1 |
| 151 | |
| 152 | 3.2.3. Challenge |
| 153 | |
| 154 | Server -> Client |
| 155 | |
| 156 | IEI Info Element Type Pres. Format Length |
| 157 | Message type 4.2.1 M V 1 |
| 158 | 20 RAND octet string (16) M TLV 18 |
| 159 | 23 AUTN octet string (16) M TLV 18 |
| 160 | |
| 161 | 3.2.4. Challenge Error |
| 162 | |
| 163 | Client -> Server |
| 164 | |
| 165 | IEI Info Element Type Pres. Format Length |
| 166 | Message type 4.2.1 M V 1 |
| 167 | 02 Cause GMM cause, M TLV 3 |
| 168 | 04.08: 10.5.5.14 |
| 169 | |
| 170 | 3.2.5. Challenge Result |
| 171 | |
| 172 | Client -> Server |
| 173 | |
| 174 | IEI Info Element Type Pres. Format Length |
| 175 | Message type 4.2.1 M V 1 |
| 176 | 21 XRES octet string (8) M TLV 10 |
| 177 | |
| 178 | 3.2.3. Sync Request |
| 179 | |
| 180 | Client -> Server |
| 181 | |
| 182 | IEI Info Element Type Pres. Format Length |
| 183 | Message type 4.2.1 M V 1 |
| 184 | 20 AUTS octet string (16) M TLV 18 |
| 185 | |
| 186 | 3.2.4. Sync Error |
| 187 | |
| 188 | Server -> Client |
| 189 | |
| 190 | IEI Info Element Type Pres. Format Length |
| 191 | Message type 4.2.1 M V 1 |
| 192 | 02 Cause GMM cause, M TLV 3 |
| 193 | 04.08: 10.5.5.14 |
| 194 | |
| 195 | 4. Information Elements |
| 196 | |
| 197 | 4.1. General |
| 198 | |
| 199 | [...] |
| 200 | |
| 201 | 4.2.1. Message Type |
| 202 | |
| 203 | +---------------------------------------------------+ |
| 204 | | 8 7 6 5 4 3 2 1 | |
| 205 | | | |
| 206 | | 0 0 0 0 0 1 0 0 - Register Request | |
| 207 | | 0 0 0 0 0 1 0 1 - Register Error | |
| 208 | | 0 0 0 0 0 1 1 0 - Register Result | |
| 209 | | | |
| 210 | | 0 0 0 0 1 0 0 0 - Challenge Request | |
| 211 | | 0 0 0 0 1 0 0 1 - Challenge Error | |
| 212 | | 0 0 0 0 1 0 1 0 - Challenge Result | |
| 213 | | | |
| 214 | | 0 0 0 0 1 1 0 0 - Sync Request | |
| 215 | | 0 0 0 0 1 1 0 1 - Sync Error (not used) | |
| 216 | | 0 0 0 0 1 1 1 0 - Sync Result (not used) | |
| 217 | | | |
| 218 | +---------------------------------------------------+ |
| 219 | |
| 220 | 4.2.2. IE Identifier (informational) |
| 221 | |
| 222 | These are the standard values for the IEI. |
| 223 | |
| 224 | +---------------------------------------------------------+ |
| 225 | | IEI Info Element Type | |
| 226 | | | |
| 227 | | 0x02 Cause GMM cause, 04.08: 10.5.5.14 | |
| 228 | | 0x20 RAND octet string | |
| 229 | | 0x23 AUTN octet string | |
| 230 | | 0x24 XRES octet string | |
| 231 | | 0x25 AUTS octet string | |
| 232 | | 0x30 Client ID big endian int (2 octets) | |
| 233 | +---------------------------------------------------------+ |
| 234 | |
| 235 | 4.2.3. Client ID |
| 236 | |
| 237 | 8 7 6 5 4 3 2 1 |
| 238 | +-----------------------------------------------------+ |
| 239 | | | Client ID IEI | octet 1 |
| 240 | +-----------------------------------------------------+ |
| 241 | | Length of Client ID IE contents (2) | octet 2 |
| 242 | +-----------------------------------------------------+ |
| 243 | | Client ID number, most significant byte | octet 3 |
| 244 | +-----------------------------------------------------+ |
| 245 | | Client ID number, least significant byte | octet 4 |
| 246 | +-----------------------------------------------------+ |
| 247 | |
| 248 | The Client ID number shall be interpreted as an unsigned 16bit integer, where 0 |
| 249 | indicates an invalid / unset ID. |
| 250 | |