diff options
| -rw-r--r-- | openbsc/doc/control-interface.txt | 21 | ||||
| -rw-r--r-- | openbsc/doc/osmocom-authn-protocol.txt | 250 | ||||
| -rw-r--r-- | openbsc/doc/sgsn-remote-protocol.txt | 468 |
3 files changed, 0 insertions, 739 deletions
diff --git a/openbsc/doc/control-interface.txt b/openbsc/doc/control-interface.txt deleted file mode 100644 index b43cafc35..000000000 --- a/openbsc/doc/control-interface.txt +++ /dev/null @@ -1,21 +0,0 @@ -The protocol for the control interface is wrapped inside the ip.access header -with the IPAC_PROTO_OSMO protocol ID (0xee). Inside the ip.access header is -a struct ipaccess_head_ext with protocol ID 0x00 which indicates the control -interface. - -After that the actual protocol is text based: - -* Getting the value of a variable --> GET <id> <var> -<- GET_REPLY <id> <var> <val> -or ERROR <id> <reason> - -* Setting the value of a variable --> SET <id> <var> <val> -<- SET_REPLY <id> <var> <val> -or ERROR <id> <reason> - -* A value changes which triggers a trap -<- TRAP <var> <val> - -<id> needs to be unique within a connection. '0' is not allowed diff --git a/openbsc/doc/osmocom-authn-protocol.txt b/openbsc/doc/osmocom-authn-protocol.txt deleted file mode 100644 index 1b6794e8d..000000000 --- a/openbsc/doc/osmocom-authn-protocol.txt +++ /dev/null @@ -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.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. - diff --git a/openbsc/doc/sgsn-remote-protocol.txt b/openbsc/doc/sgsn-remote-protocol.txt deleted file mode 100644 index 6591d638e..000000000 --- a/openbsc/doc/sgsn-remote-protocol.txt +++ /dev/null @@ -1,468 +0,0 @@ - - GPRS Subscriber Update Protocol - -1. General - -This document describes the remote protocol that is used by the SGSN to update -and manage the local subscriber list. The protocol and the messages are -designed after the corresponding MAP messages (see GSM 09.02) with the -following differences: - - - The encoding uses TLV structures instead of ASN.1 encodings - - Segmentation is not used - -See the specification of the Gr interface (GSM 03.60). - -2. Connection - -The protocol expects that a reliable, ordered, packet boundaries preserving -connection is used (e.g. IPA over TCP). The remote peer is either a service -that understands the protocol natively or a wrapper service that maps the -messages to/from real MAP messages that can be used to directly communicate -with an HLR. - -2.1. Using IPA - -By default, the following identifiers should be used: - - IPA protocol: 0xee (OSMO) - - IPA OSMO protocol extension: 0x05 - -2. Procedures - -2.1. Authentication management - -The SGSN sends a SEND_AUTHENTICATION_INFO_REQ message containing the MS's IMSI -to the peer. On errors, especially if authentication info is not availabe for -that IMSI, the peer returns a SEND_AUTHENTICATION_INFO_ERR message. Otherwise -the peer returns a SEND_AUTHENTICATION_INFO_RES message. If this message -contains at least one authentication tuple, the SGSN replaces all tuples that -are assigned to the subscriber. If the message doesn't contain any tuple the -SGSN may reject the Attach Request. (see GSM 09.02, 25.5.6) - -2.2. Location Updating - -The SGSN sends a UPDATE_LOCATION_REQ to the peer. If the request is denied by -the network, the peer returns an UPDATE_LOCATION_ERR message to the SGSN. -Otherwise the peer returns an UPDATE_LOCATION_RES message containing all -information fields that shall be inserted into the subscriber record. If -the 'PDP info complete' information element is set in the message, the SGSN -clears existing PDP information fields in the subscriber record first. -(see GSM 09.02, 19.1.1.8) - -[...] - -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 - 01 IMSI 4.2.9 M TLV 2-10 - -If a numeric range is indicated in the 'presence' column, multiple information -elements with the same tag may be used in sequence. The information elements -shall be sent in the given order. Nevertheless after the generic part the -receiver shall be able to received them in any order. Unknown IE shall be -ignored. - -3.2.1. Send Authentication Info Request - -SGSN -> Network peer - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - -3.2.2. Send Authentication Info Error - -Network peer -> SGSN - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - 02 Cause GMM cause, M TLV 3 - 04.08: 10.5.5.14 - -3.2.3. Send Authentication Info Response - -Network peer -> SGSN - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - 03 Auth tuple 4.2.5 0-5 TLV 36 - -3.2.4. Update Location Request - -SGSN -> Network peer - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - -3.2.5. Update Location Error - -Network peer -> SGSN - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - 02 Cause GMM cause, M TLV 3 - 04.08: 10.5.5.14 - -3.2.6. Update Location Result - -Network peer -> SGSN - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - 08 MSISDN 4.2.10 O TLV 0-9 - 09 HLR Number 4.2.12 O TLV 0-9 - 04 PDP info complete 4.2.8 O TLV 2 - 05 PDP info 4.2.3 1-10 TLV - -If the PDP info complete IE is present, the old PDP info list shall be cleared. - -3.2.7. Location Cancellation Request - -Network peer -> SGSN - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - 06 Cancellation type 4.2.6 M TLV 3 - -3.2.8. Location Cancellation Result - -SGSN -> Network peer - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - -3.2.9. Purge MS Request - -SGSN -> Network peer - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - 09 HLR Number 4.2.12 M TLV 0-9 - -3.2.10. Purge MS Error - -Network peer -> SGSN - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - 02 Cause GMM cause, M TLV 3 - 04.08: 10.5.5.14 - -3.2.11. Purge MS Result - -Network peer -> SGSN - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - 07 Freeze P-TMSI 4.2.8 O TLV 2 - -3.2.12. Insert Subscriber Data Request - -Network peer -> SGSN - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - 04 PDP info complete 4.2.8 O TLV 2 - 05 PDP info 4.2.3 0-10 TLV - -If the PDP info complete IE is present, the old PDP info list shall be cleared. - -3.2.13. Insert Subscriber Data Error - -SGSN -> Network peer - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - 02 Cause GMM cause, M TLV 3 - 04.08: 10.5.5.14 - -3.2.14. Insert Subscriber Data Result - -SGSN -> Network peer - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - -3.2.15. Delete Subscriber Data Request - -Network peer -> SGSN - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - 10 PDP context id 4.2.3 0-10 TLV - (no conditional IE) - -3.2.16. Delete Subscriber Data Error - -SGSN -> Network peer - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - 02 Cause GMM cause, M TLV 3 - 04.08: 10.5.5.14 - -3.2.17. Delete Subscriber Data Result - -Network peer -> SGSN - - IEI Info Element Type Pres. Format Length - Message type 4.2.1 M V 1 - 01 IMSI 4.2.9 M TLV 2-10 - -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 - Update Location Request | - | 0 0 0 0 0 1 0 1 - Update Location Error | - | 0 0 0 0 0 1 1 0 - Update Location Result | - | | - | 0 0 0 0 1 0 0 0 - Send Auth Info Request | - | 0 0 0 0 1 0 0 1 - Send Auth Info Error | - | 0 0 0 0 1 0 1 0 - Send Auth Info Result | - | | - | 0 0 0 0 1 1 0 0 - Purge MS Request | - | 0 0 0 0 1 1 0 1 - Purge MS Error | - | 0 0 0 0 1 1 1 0 - Purge MS Result | - | | - | 0 0 0 1 0 0 0 0 - Insert Subscr. Data Request | - | 0 0 0 1 0 0 0 1 - Insert Subscr. Data Error | - | 0 0 0 1 0 0 1 0 - Insert Subscr. Data Result | - | | - | 0 0 0 1 0 1 0 0 - Delete Subscr. Data Request | - | 0 0 0 1 0 1 0 1 - Delete Subscr. Data Error | - | 0 0 0 1 0 1 1 0 - Delete Subscr. Data Result | - | | - | 0 0 0 1 1 1 0 0 - Location Cancellation Request | - | 0 0 0 1 1 1 0 1 - Location Cancellation Error | - | 0 0 0 1 1 1 1 0 - Location Cancellation Result | - | | - +---------------------------------------------------+ - -4.2.2. IP Address - -The value part is encoded like in the Packet data protocol address IE defined -in GSM 04.08, 10.5.6.4. PDP type organization must be set to 'IETF allocated -address'. - -4.2.3. PDP Info - -This is a container for information elements describing a single PDP. - - IEI Info Element Type Pres. Format Length - PDP Info IEI M V 1 - Length of PDP Info IE length, no ext M V 1 - 10 PDP context id big endian int, 1-N C TLV 3 - 11 PDP type 4.2.4 C TLV 4 - 12 Access point name 04.08, 10.5.6.1 C TLV 3-102 - 13 Quality of Service 4.2.11 O TLV 1-20 - -The conditional IE are mandantory unless mentioned otherwise. - -4.2.4. PDP Type - -The PDP type value consists of 2 octets that are encoded like octet 4-5 of the -End User Address defined in GSM 09.60, 7.9.18. - - 8 7 6 5 4 3 2 1 - +-----------------------------------------------------+ - | | PDP type IEI | octet 1 - +-----------------------------------------------------+ - | Length of PDP type IE contents (2) | octet 2 - +-----------------------------------------------------+ - | Spare | PDP type org. | octet 3 - +-----------------------------------------------------+ - | PDP type number | octet 4 - +-----------------------------------------------------+ - -The spare bits are left undefined. While 09.60 defines them as '1 1 1 1', there -are MAP traces where these bits are set to '0 0 0 0'. So the receiver shall -ignore these bits. - -Examples: - - IPv4: PDP type org: 1 (IETF), PDP type number: 0x21 - IPv6: PDP type org: 1 (IETF), PDP type number: 0x57 - -4.2.5. Auth tuple - -This is a container for information elements describing a single authentication -tuple. - -IEI Info Element Type Pres. Format Length - Auth. Tuple IEI M V 1 - Length of Ath Tuple IE length, no ext M V 1 -20 RAND octet string (16) M TLV 18 -21 SRES octet string (4) M TLV 6 -22 Kc octet string (8) M TLV 10 - -4.2.6. Cancellation Type - - 8 7 6 5 4 3 2 1 - +-----------------------------------------------------+ - | | Cancellation type IEI | octet 1 - +-----------------------------------------------------+ - | Length of Cancellation Type IE contents (1) | octet 2 - +-----------------------------------------------------+ - | Cancellation type number | octet 4 - +-----------------------------------------------------+ - -Where the cancellation type number is: - - +---------------------------------------------------+ - | 8 7 6 5 4 3 2 1 | - | | - | 0 0 0 0 0 0 0 0 - Update Procedure | - | 0 0 0 0 0 0 0 1 - Subscription Withdraw | - +---------------------------------------------------+ - -4.2.7. IE Identifier (informational) - -These are the standard values for the IEI. See the message definitions for the -IEI that shall be used for the encoding. - - +---------------------------------------------------------+ - | IEI Info Element Type | - | | - | 0x01 IMSI Mobile identity, 04.08: 10.5.1.4 | - | 0x02 Cause GMM cause, 04.08: 10.5.5.14 | - | 0x03 Auth tuple 4.2.5 | - | 0x04 PDP info compl 4.2.8 | - | 0x05 PDP info 4.2.3 | - | 0x06 Cancel type 4.2.6 | - | 0x07 Freeze P-TMSI 4.2.8 | - | 0x08 MSISDN ISDN-AddressString/octet, 4.2.10 | - | 0x09 HLR Number 4.2.12 | - | 0x10 PDP context id big endian int | - | 0x11 PDP type 4.2.4 | - | 0x12 APN 04.08, 10.5.6.1 | - | 0x13 QoS 4.2.11 | - | 0x20 RAND octet string | - | 0x21 SRES octet string | - | 0x22 Kc octet string | - +---------------------------------------------------------+ - - -4.2.8 Empty field - -This is used for flags, if and only if this IE is present, the flag is set. -The semantics depend on the IEI and the context. - - 8 7 6 5 4 3 2 1 - +-----------------------------------------------------+ - | | IEI | octet 1 - +-----------------------------------------------------+ - | Length of IE contents (0) | octet 2 - +-----------------------------------------------------+ - -4.2.9. IMSI - -The IMSI is encoded like in octet 4-N of the Called Party BCD Number defined in GSM 04.08, 10.5.4.7. - - 8 7 6 5 4 3 2 1 - +-----------------------------------------------------+ - | | IMSI IEI | octet 1 - +-----------------------------------------------------+ - | Length of IMSI IE contents | octet 2 - +-----------------------------------------------------+ - | Number digit 2 | Number digit 1 | octet 3 - +-----------------------------------------------------+ - | Number digit 4 | Number digit 3 | octet 4 - +-----------------------------------------------------+ - : : : - +-----------------------------------------------------+ - | see note 1) | octet 2+(N+1)div2 - +-----------------------------------------------------+ - -Note 1) Either '1 1 1 1 | Number digit N' (N odd) or - 'Number digit N | Number digit N-1' (N even), - where N is the number of digits. - -4.2.10. ISDN-AddressString / MSISDN / Called Party BCD Number - -The MSISDN is encoded as an ISDN-AddressString in GSM 09.02 and Called Party -BCD Number in GSM 04.08. It will be stored by the SGSN and then passed as is -to the GGSN during the activation of the primary PDP Context. - - 8 7 6 5 4 3 2 1 - +-----------------------------------------------------+ - | | IEI | octet 1 - +-----------------------------------------------------+ - | Length of IE contents | octet 2 - +-----------------------------------------------------+ - | ext | Type of num | Numbering plan | octet 2 - +-----------------------------------------------------+ - | Number digit 2 | Number digit 1 | octet 3 - +-----------------------------------------------------+ - | Number digit 4 | Number digit 3 | octet 4 - +-----------------------------------------------------+ - : : : - +-----------------------------------------------------+ - - -4.2.11 Quality of Service Subscribed Service - -This encodes the subscribed QoS of a subscriber. It will be used by the -SGSN during the PDP Context activation. If the length of the QoS data -is 3 (three) octets it is assumed that these are octets 3-5 of the TS -3GPP TS 24.008 Quality of Service Octets. If it is more than three then -then it is assumed that the first octet is the Allocation/Retention -Priority and the reset are encoded as octets 3-N of 24.008. - - - 8 7 6 5 4 3 2 1 - +-----------------------------------------------------+ - | | IEI | octet 1 - +-----------------------------------------------------+ - | Length of IE contents | octet 2 - +-----------------------------------------------------+ - : : : - +-----------------------------------------------------+ - -4.2.12. HLR Number encoded as GSM 09.02 ISDN-AddressString - -The HLR Number is encoded as an ISDN-AddressString in GSM 09.02. It -will be stored by the SGSN can be used by the CDR module to keep a -record. - - 8 7 6 5 4 3 2 1 - +-----------------------------------------------------+ - | | IEI | octet 1 - +-----------------------------------------------------+ - | Length of IE contents | octet 2 - +-----------------------------------------------------+ - | ext | Type of num | Numbering plan | octet 2 - +-----------------------------------------------------+ - | Number digit 2 | Number digit 1 | octet 3 - +-----------------------------------------------------+ - | Number digit 4 | Number digit 3 | octet 4 - +-----------------------------------------------------+ - : : : - +-----------------------------------------------------+ |