1 files changed, 592 insertions, 0 deletions
diff --git a/doc/manuals/chapters/gsup.adoc b/doc/manuals/chapters/gsup.adoc
new file mode 100644
index 000000000..9efc8c096
--- /dev/null
+++ b/doc/manuals/chapters/gsup.adoc
@@ -0,0 +1,592 @@
+[[gsup]]
+== GPRS Subscriber Update Protocol
+
+=== General
+
+This chapter 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 3GPP TS 09.02) with the
+following differences:
+
+* The encoding uses TLV structures instead of ASN.1 encodings
+* Segmentation is not used
+
+For more information, see the specification of the Gr interface (3GPP TS 03.60).
+
+=== 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.
+
+=== Using IPA
+
+By default, the following identifiers should be used:
+
+* IPA Stream ID: 0xEE (OSMO)
+* IPA OSMO protocol extension: 0x05
+
+For more information about the IPA multiplex, please see the 'OsmoBTS
+Abis/IP Specifiation'.
+
+=== Procedures
+
+==== 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 3GPP TS 09.02, 25.5.6)
+
+==== 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 3GPP TS 09.02, 19.1.1.8)
+
+...
+
+=== Message Format
+
+==== General
+
+Every message is based on the following message format
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|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.
+
+==== Send Authentication Info Request
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|===
+
+==== Send Authentication Info Error
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|02|Cause|<<gsup-ie-cause>>|M|TLV|3
+|===
+
+==== Send Authentication Info Response
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|03|Auth Tuple|<<gsup-ie-authtuple>>|0-5|TLV|36
+|===
+
+==== Update Location Request
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|===
+
+==== Update Location Error
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|02|Cause|<<gsup-ie-cause>>|M|TLV|3
+|===
+
+==== Update Location Result
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|08|MSISDN|<<gsup-ie-msisdn>>|O|TLV|0-9
+|09|HLR Number|<<gsup-ie-hlr>>|O|TLV|0-9
+|04|PDP info complete|<<gsup-ie-empty>>|O|TLV|2
+|05|PDP info|<<gsup-ie-pdpinfo>>|1-10|TLV|
+|===
+
+If the PDP info complete IE is present, the old PDP info list shall be cleared.
+
+==== Location Cancellation Request
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|06|Cancellation type|<<gsup-ie-canctype>>|O|TLV|3
+|===
+
+==== Location Cancellation Result
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|===
+
+==== Purge MS Request
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|09|HLR Number|<<gsup-ie-hlr>>|M|TLV|0-9
+|===
+
+==== Purge MS Error
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|02|Cause|<<gsup-ie-cause>>|M|TLV|3
+|===
+
+==== Purge MS Result
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|07|Freeze P-TMSI|<<gsup-ie-empty>>|M|TLV|2
+|===
+
+==== Insert Subscriber Data Request
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|04|PDP info complete|<<gsup-ie-empty>>|M|TLV|2
+|05|PDP info|<<gsup-ie-pdpinfo>>|0-10|TLV|
+|===
+
+If the PDP info complete IE is present, the old PDP info list shall be cleared.
+
+==== Insert Subscriber Data Error
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|02|Cause|<<gsup-ie-cause>>|M|TLV|3
+|===
+
+==== Insert Subscriber Data Result
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|===
+
+==== Delete Subscriber Data Request
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|10|PDP context id|<<gsup-ie-pdpinfo>> (no conditional IE)|0-10|TLV|
+|===
+
+==== Delete Subscriber Data Error
+
+Direction: SGSN -> Network peer
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|02|Cause|<<gsup-ie-cause>>|M|TLV|3
+|===
+
+==== Delete Subscriber Data Result
+
+Direction: Network peer -> SGSN
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Message Type|<<gsup-ie-msgtype>>|M|V|1
+|01|IMSI|<<gsup-ie-imsi>>|M|TLV|2-10
+|===
+
+=== Information Elements
+
+[[gsup-ie-msgtype]]
+==== Message Type
+
+[options="header",cols="10%,90%"]
+|===
+|Type|Description
+|0x04|Update Location Request
+|0x05|Update Location Error
+|0x06|Update Location Result
+|0x08|Send Auth Info Request
+|0x09|Send Auth Info Error
+|0x0a|Send Auth Info Result
+|0x0c|Purge MS Request
+|0x0d|Purge MS Error
+|0x0e|Purge MS Result
+|0x10|Insert Subscriber Data Request
+|0x11|Insert Subscriber Data Error
+|0x12|Insert Subscriber Data Result
+|0x14|Delete Subscriber Data Request
+|0x15|Delete Subscriber Data Error
+|0x16|Delete Subscriber Data Result
+|0x1c|Location Cancellation Request
+|0x1d|Location Cancellation Error
+|0x1e|Location Cancellation Result
+|===
+
+[[gsup-ie-ipaddr]]
+==== IP Address
+
+The value part is encoded like in the Packet data protocol address IE defined
+in 3GPP TS 04.08, Chapter 10.5.6.4. PDP type organization must be set to
+'IETF allocated address'.
+
+[[gsup-ie-pdpinfo]]
+==== PDP Info
+
+This is a container for information elements describing a single PDP.
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |PDP Info IEI|<<gsup-iei>>|M|V|1
+|  |Length of PDP Info IE||M|V|1
+|10|PDP Context ID|<<gsup-ie-pdpctxid>>|C|TLV|3
+|11|PDP Type|<<gsup-ie-pdptype>>|C|TLV|4
+|12|Access Point Name|3GPP TS 04.08, Ch. 10.5.6.1|C|TLV|3-102
+|13|Quality of Service|<<gsup-ie-qos>>|O|TLV|1-20
+|===
+
+The conditional IE are mandantory unless mentioned otherwise.
+
+[[gsup-ie-pdptype]]
+==== PDP Type
+
+The PDP type value consists of 2 octets that are encoded like octet 4-5 of the
+End User Address defined in 3GPP TS 09.60, 7.9.18.
+
+[packetdiag]
+----
+{
+	colwidth = 8
+	node_height = 24
+
+	0-6:	PDP type IEI
+	7:	Res
+	8-15:	Length (2)
+	16-19:	Spare
+	20-23:	PDP type org
+	24-31:	PDP type number
+}
+----
+
+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
+
+[[gsup-ie-pdpctxid]]
+==== PDP Context ID
+
+The PDP type context ID IE consists of a single integer byte wrapped in
+a TLV.
+
+[packetdiag]
+----
+{
+	colwidth = 8
+	node_height = 24
+
+	0-6:	PDP context ID IEI
+	7:	Res
+	8-15:	Length (1)
+	16-23:	PDP Context ID
+}
+----
+
+[[gsup-ie-authtuple]]
+==== Auth tuple
+
+This is a container for information elements describing a single authentication
+tuple.
+
+[options="header",cols="5%,20%,45%,10%,10%,10%"]
+|===
+|IEI|IE|Type|Presence|Format|Length
+|  |Auth Tuple IEI|<<gsup-iei>>|M|V|1
+|  |Length of Auth Tuple IE||M|V|1
+|20|RAND|<<gsup-ie-rand>>|M|TLV|18
+|21|SRES|<<gsup-ie-sres>>|M|TLV|6
+|22|Kc|<<gsup-ie-kc>>|M|TLV|10
+|===
+
+[[gsup-ie-rand]]
+==== RAND
+
+The 16-byte Random Challenge of the GSM Authentication Algorithm.
+
+[[gsup-ie-sres]]
+==== SRES
+
+The 4-byte Authentication Result of the GSM Authentication Algorithm.
+
+[[gsup-ie-kc]]
+==== Kc
+
+The 8-byte Encryption Key of the GSM Authentication and Key Agreemnt
+Algorithm.
+
+[[gsup-ie-canctype]]
+==== Cancellation Type
+
+[packetdiag]
+----
+{
+	colwidth = 8
+	node_height = 24
+
+	0-6:	PDP type IEI
+	7:	Res
+	8-15:	Length (1)
+	16-23:	Canc. Type Nr.
+}
+----
+
+.Cancellation Type Number
+[options="header",cols="10%,90%"]
+|===
+|Number|Description
+|0x00|Update Procedure
+|0x01|Subscription Withdrawn
+|===
+
+[[gsup-iei]]
+==== 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.
+
+.GSUP IE Identifiers
+[options="header",cols="15%,35%,50%"]
+|===
+|IEI|Info Element|Type / Encoding
+|0x01|IMSI|Mobile Identity, 3GPP TS 04.08 Ch. 10.5.1.4
+|0x02|Cause|<<gsup-ie-cause>>
+|0x03|Auth Tuple|<<gsup-ie-authtuple>>
+|0x04|PDP Info Compl|<<gsup-ie-empty>>
+|0x05|PDP Info|<<gsup-ie-pdpinfo>>
+|0x06|Cancel Type|<<gsup-ie-canctype>>
+|0x07|Freeze P-TMSI|<<gsup-ie-empty>>
+|0x08|MSISDN|ISDN-AddressString/octet, <<gsup-ie-msisdn>>
+|0x09|HLR Number|<<gsup-ie-hlr>>
+|0x10|PDP Context ID|<<gsup-ie-pdpctxid>>
+|0x11|PDP Type|<<gsup-ie-pdptype>>
+|0x12|QoS|<<gsup-ie-qos>>
+|0x20|RAND|<<gsup-ie-rand>>
+|0x21|SRES|<<gsup-ie-sres>>
+|0x22|Kc|<<gsup-ie-kc>>
+|===
+
+[[gsup-ie-empty]]
+==== 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.
+
+[packetdiag]
+----
+{
+	colwidth = 8
+	node_height = 24
+
+	0-6:	PDP type IEI
+	7:	Res
+	8-15:	Length (0)
+}
+----
+
+[[gsup-ie-imsi]]
+==== IMSI
+
+The IMSI is encoded like in octet 4-N of the Called Party BCD Number
+defined in 3GPP TS 04.08, 10.5.4.7.
+
+[packetdiag]
+----
+{
+	colwidth = 8
+	node_height = 24
+
+	0-6:	PDP type IEI
+	7:	Res
+	8-15:	Length of IE content
+	16-19:	Digit 1
+	20-23:	Digit 2
+	24-27:	Digit ...
+	28-31:	Digit N
+	32-39:  see Note
+}
+----
+
+NOTE: 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.
+
+[[gsup-ie-msisdn]]
+==== ISDN-AddressString / MSISDN / Called Party BCD Number
+
+The MSISDN is encoded as an ISDN-AddressString in 3GPP TS 09.02 and Called Party
+BCD Number in 3GPP TS 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.
+
+[packetdiag]
+----
+{
+	colwidth = 8
+	node_height = 24
+
+	0-6:	PDP type IEI
+	7:	Res
+	8-15:	Length of IE content
+	16-19:	NPI
+	20-22:	TON
+	23:	ext
+	24-27:	Digit 1
+	28-31:	Digit 2
+	32-35:	Digit ...
+	36-39:	Digit N
+}
+----
+
+[[gsup-ie-qos]]
+==== 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.
+
+[packetdiag]
+----
+{
+	colwidth = 8
+	node_height = 24
+
+	0-6:	PDP type IEI
+	7:	Res
+	8-15:	Length of IE content
+	16-23:	Payload
+}
+----
+
+[[gsup-ie-hlr]]
+==== HLR Number encoded as 3GPP TS 09.02 ISDN-AddressString
+
+The HLR Number is encoded as an ISDN-AddressString in 3GPP TS 09.02. It
+will be stored by the SGSN can be used by the CDR module to keep a
+record.
+
+[packetdiag]
+----
+{
+	colwidth = 8
+	node_height = 24
+
+	0-6:	PDP type IEI
+	7:	Res
+	8-15:	Length of IE content
+	16-19:	NPI
+	20-22:	TON
+	23:	ext
+	24-27:	Digit 1
+	28-31:	Digit 2
+	32-35:	Digit ...
+	36-39:	Digit N
+}
+----
+
+[[gsup-ie-cause]]
+==== Cause
+
+This IE shall be encoded according to the 'GMM Cause' as described in
+Chapter 10.5.5.14 of 3GPP TS 04.08.