sgsn/doc: Add protocol specification for remote subscriber update
This is the first version of the specification for the GPRS
Subscriber Update Protocol.
Sponsored-by: On-Waves ehf
diff --git a/openbsc/doc/sgsn-remote-protocol.txt b/openbsc/doc/sgsn-remote-protocol.txt
new file mode 100644
index 0000000..7ca9094
--- /dev/null
+++ b/openbsc/doc/sgsn-remote-protocol.txt
@@ -0,0 +1,385 @@
+
+ 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. 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
+ 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
+
+3.2.10. Purge MS Error
+
+Network peer -> SGSN
+
+TODO
+
+3.2.11. Purge MS Result
+
+Network peer -> SGSN
+
+TODO
+
+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
+
+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 |
+ | 0x10 PDP context id big endian int |
+ | 0x11 PDP type 4.2.4 |
+ | 0x12 APN 04.08, 10.5.6.1 |
+ | 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.