[[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 Specification'.

=== 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 available 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
|28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3
|26|AUTS|<<gsup-ie-auts>>|C|TLV|18
|20|RAND|<<gsup-ie-rand>>|C|TLV|18
|===

The conditional 'AUTS' and 'RAND' IEs are both present in case the SIM
(via UE) requests an UMTS AKA re-synchronization procedure.  Eiter
both optional IEs are present, or none of them.

==== 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
|===

==== Authentication Failure Report

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
|28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3
|===

==== 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
|28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3
|===

==== 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
|28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3
|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
|28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3
|===

==== 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
|28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3
|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
|28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3
|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>>|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
|28|CN Domain|<<gsup-ie-cndomain>>|O|TLV|3
|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
|0x0b|Authentication Failure Report
|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
|23|IK|<<gsup-ie-ik>>|C|TLV|18
|24|CK|<<gsup-ie-ck>>|C|TLV|18
|25|AUTN|<<gsup-ie-autn>>|C|TLV|18
|27|RES|<<gsup-ie-res>>|C|TLV|2-18
|===

The conditional IEs 'IK', 'CK', 'AUTN' and 'RES' are onl present in
case the subscriber supports UMTS AKA.

[[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-ik]]
==== IK

The 16-byte Integrity Protection Key generated by the UMTS
Authentication and Key Agreement Algorithm.

[[gsup-ie-ck]]
==== CK

The 16-byte Ciphering Key generated by the UMTS Authentication and Key
Agreement Algorithm.

[[gsup-ie-autn]]
==== AUTN

The 16-byte Authentication Nonce sent from network to USIM in the UMTS
Authentication and Key Agreement Algorithm.

[[gsup-ie-auts]]
==== AUTS

The 16-byte Authentication Synchronization Nonce generated by the USIM
in case the  UMTS Authentication and Key Agreement Algorithm needs to
re-synchronize the sequence counters between AUC and USIM.

[[gsup-ie-res]]
==== RES

The (variable length, but typically 16 byte) Authentication Result
generated by the USIM in the UMTS Authentication and Key Agreement
Algorithm.

[[gsup-ie-cndomain]]
==== CN Domain

This single-byte information element indicates the Core Network
Domain, i.e. if the message is related to Circuit Switched or Packet
Switched services.

For backwards compatibility reasons, if no CN Domain IE is present
within a request, the PS Domain is assumed.

.CN Domain Number
[options="header",cols="10%,90%"]
|===
|Type|Description
|0x01|PS Domain
|0x02|CS Domain
|===

[[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>>
|0x23|IK|<<gsup-ie-ik>>
|0x24|CK|<<gsup-ie-ck>>
|0x25|AUTN|<<gsup-ie-autn>>
|0x26|AUTS|<<gsup-ie-auts>>
|0x27|RES|<<gsup-ie-res>>
|0x28|CN Domain|<<gsup-ie-cndomain>>
|===

[[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.