openbsc/doc/sgsn-remote-protocol.txt

               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
  +-----------------------------------------------------+
  :                                                     :   :
  +-----------------------------------------------------+