path: root/common/chapters/gsup.adoc

[[gsup]]
== Generic Subscriber Update Protocol

=== General

This chapter describes the remote protocol that is used by OsmoSGSN and OsmoMSC to update
and manage the local subscriber list in OsmoHLR.  Functionally, it resembles the
interface between the SGSN/VLR on the one hand side, and HLR/AUC on the
other side.

For more information, see the specification of the Gr interface (3GPP TS 03.60).

Traditionally, the GSM MAP (Mobile Application Part) protocol is used
for this purpose, running on top of a full telecom signalling protocol
stack of MTP2/MTP3/SCCP/TCAP, or any of the SIGTRAN alternatives.

In order to avoid many of the complexities of MAP, which are difficult
to implement in the plain C language environment of the Osmocom
cellular network elements like the SGSN, we introduce the GSUP
protocol.

The GSUP protocol and the messages are designed after the
corresponding MAP messages (see 3GPP TS 09.02) with the following
main differences:

* The encoding uses TLV structures instead of ASN.1 BER
* Segmentation is not used, i.e. we rely on the fact that the
  underlying transport protocol can transport signalling messages of
  any size.

=== 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 or VLR 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 or VLR replaces all tuples that
are assigned to the subscriber. If the message doesn't contain any tuple the
SGSN or VLR may reject the Attach Request. (see 3GPP TS 09.02, 25.5.6)

.Send Authentication Info (Normal Case)
["mscgen"]
----
msc {
  hscale="1.5";
  SGSN [label="SGSN/VLR"], Peer [label="Network Peer (HLR)"];

  SGSN => Peer [label="SEND AUTHENTICATION INFO REQUEST (IMSI)"];
  Peer => SGSN [label="SEND AUTHENTICATION INFO RESPONSE (Tuples)"];
}
----

.Send Authentication Info (Erroneous Case)
["mscgen"]
----
msc {
  hscale="1.5";
  SGSN [label="SGSN/VLR"], Peer [label="Network Peer (HLR)"];

  SGSN => Peer [label="SEND AUTHENTICATION INFO REQUEST (IMSI)"];
  Peer => SGSN [label="SEND AUTHENTICATION INFO ERROR (Cause)"];
}
----

==== Reporting of Authentication Failure

Using this procedure, the SGSN or VLR reports authentication failures to the
HLR.

.Authentication Failure Report (Normal Case)
["mscgen"]
----
msc {
  hscale="1.5";
  SGSN [label="SGSN/VLR"], Peer [label="Network Peer (HLR)"];

  SGSN => Peer [label="AUTHENTICATION FAILURE REPORT (IMSI)"];
}
----

==== Location Updating

The SGSN or VLR 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 or VLR.
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 or VLR
clears existing PDP information fields in the subscriber record first.
(see 3GPP TS 09.02, 19.1.1.8)

.Update Location (Normal Case)
["mscgen"]
----
msc {
  hscale="1.5";
  SGSN [label="SGSN/VLR"], Peer [label="Network Peer (HLR)"];

  SGSN => Peer [label="UPDATE LOCATION REQUEST (IMSI)"];
  Peer => SGSN [label="INSERT SUBSCRIBER DATA"];
  SGSN => Peer [label="INSERT SUBSCRIBER DATA ACK"];
  Peer => SGSN [label="UPDATE LOCATTION RESULT"];
}
----

.Update Location (Error Case)
["mscgen"]
----
msc {
  hscale="1.5";
  SGSN [label="SGSN/VLR"], Peer [label="Network Peer (HLR)"];

  SGSN => Peer [label="UPDATE LOCATION REQUEST (IMSI)"];
  Peer => SGSN [label="UPDATE LOCATTION ERROR (Cause)"];
}
----

==== Location Cancellation

Using the Location Cancellation procedure, the Network Peer (HLR) can
request the SGSN or VLR to remove a subscriber record.

.Cancel Location (Normal Case)
["mscgen"]
----
msc {
  hscale="1.5";
  SGSN [label="SGSN/VLR"], Peer [label="Network Peer (HLR)"];

  Peer => SGSN [label="CANCEL LOCATION REQUEST (IMSI)"];
  SGSN => Peer [label="CANCEL LOCATION RESULT"];
}
----

.Cancel Location (Error Case)
["mscgen"]
----
msc {
  hscale="1.5";
  SGSN [label="SGSN/VLR"], Peer [label="Network Peer (HLR)"];

  Peer => SGSN [label="CANCEL LOCATION REQUEST (IMSI)"];
  SGSN => Peer [label="CANCEL LOCATION ERROR (Cause)"];
}
----

==== Purge MS

Using the Purge MS procedure, the SGSN or VLR can request purging of MS
related state from a previous SGSN or VLR during an inter-SGSN / inter-MSC location
update.

.Purge MS (Normal Case)
["mscgen"]
----
msc {
  hscale="1.5";
  SGSN [label="SGSN/VLR"], Peer [label="Network Peer (HLR)"];

  SGSN => Peer [label="PURGE MS REQUEST (IMSI)"];
  Peer => SGSN [label="PURGE MS RESULT"];
}
----

==== Delete Subscriber Data

Using the Delete Subscriber Data procedure, the Peer (HLR) can remove
some of the subscriber data from the SGSN or VLR.  This is used in case the
subscription details (e.g. PDP Contexts / APNs) change while the
subscriber is registered to that SGSN VLR.

.Delete Subscriber Data (Normal Case)
["mscgen"]
----
msc {
  hscale="1.5";
  SGSN [label="SGSN/VLR"], Peer [label="Network Peer (HLR)"];

  Peer => SGSN [label="DELETE SUBSCRIBER DATA REQUEST (IMSI)"];
  SGSN => Peer [label="DELETE SUBSCRIBER DATA RESULT"];
}
----

==== Check IMEI

The VLR asks the EIR to check if a new ME's IMEI is acceptable or not. The EIR
may implement a blacklist or whitelist and reject the IMEI based on that.
Against the original purpose of the Check IMEI Procedure, this could also be
used to save the IMEI in the HLR DB.

.Check IMEI (Normal Case)
["mscgen"]
----
msc {
  hscale="1.5";
  VLR [label="VLR"], EIR [label="EIR (via HLR)"];

  VLR => EIR [label="CHECK IMEI REQUEST (IMEI)"];
  EIR => VLR [label="CHECK IMEI RESULT (ACK)"];
}
----

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

Besides a numeric range, the 'presence' column may have 'M' (Mandatory), 'O'
(Optional) or 'C' (Conditional). The 'format' column holds either 'V' (Value)
or 'TLV' (Tag Length Value).

==== Send Authentication Info Request

Direction: SGSN / VLR => HLR

[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: HLR => SGSN / VLR

[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: HLR => SGSN / VLR

[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 / VLR => HLR

[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 / VLR => HLR

[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: HLR => SGSN / VLR

[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: HLR => SGSN / VLR

[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: HLR => SGSN / VLR

[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 / VLR => HLR

[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 / VLR => HLR

[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: HLR => SGSN / VLR

[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: HLR => SGSN / VLR

[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: HLR => SGSN / VLR

[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|
|14|PDP-Charging Characteristics|<<gsup-ie-charging>>|O|TLV|4
|===

If the PDP info complete IE is present, the old PDP info list shall be cleared.

==== Insert Subscriber Data Error

Direction: SGSN / VLR => HLR

[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 / VLR => HLR

[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: HLR => SGSN / VLR

[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 / VLR => HLR

[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: HLR => SGSN / VLR

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

==== Process Supplementary Service Request

Direction: bidirectional

[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
|30|Session ID|<<gsup-ie-session-id>>|M|TLV|6
|31|Session State|<<gsup-ie-session-state>>|M|TLV|3
|35|Supplementary Service Info|<<gsup-ie-ss-info>>|O|TLV|2-...
|===

This message is used in both directions in case of USSD, because
it is not known is it request or response without parsing
the GSM 04.80 payload.

==== Process Supplementary Service Error

Direction: EUSE / HLR => MSC

[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
|30|Session ID|<<gsup-ie-session-id>>|M|TLV|6
|31|Session State|<<gsup-ie-session-state>>|M|TLV|3
|02|Cause|<<gsup-ie-cause>>|M|TLV|3
|===

==== Process Supplementary Service Response

Direction: EUSE / HLR => MSC

[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
|30|Session ID|<<gsup-ie-session-id>>|M|TLV|6
|31|Session State|<<gsup-ie-session-state>>|M|TLV|3
|35|Supplementary Service Info|<<gsup-ie-ss-info>>|O|TLV|2-...
|===

The purpose of this message is not clear yet. Probably, it
can be used to notify the MSC that a structured supplementary
service is successfully activated or deactivated, etc.

==== MO-forwardSM Request

Direction: MSC / SGSN => SMSC (via HLR)

[options="header",cols="5%,45%,20%,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
|40|SM-RP-MR (Message Reference)|<<gsup-ie-sm-rp-mr>>|M|TLV|1
|41|SM-RP-DA (Destination Address)|<<gsup-ie-sm-rp-da>>|M|TLV|2-...
|42|SM-RP-OA (Originating Address)|<<gsup-ie-sm-rp-oa>>|M|TLV|2-...
|43|SM-RP-UI (SM TPDU)|<<gsup-ie-sm-rp-ui>>|M|TLV|1-...
|===

This message is used to forward MO short messages from MSC / SGSN to an SMSC.
The corresponding MAP service is MAP-MO-FORWARD-SHORT-MESSAGE,
see 3GPP TS 29.002, section 12.2.

==== MO-forwardSM Error

Direction: SMSC (via HLR) => MSC / SGSN

[options="header",cols="5%,45%,20%,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
|40|SM-RP-MR (Message Reference)|<<gsup-ie-sm-rp-mr>>|M|TLV|1
|44|SM-RP-Cause (Cause value)|<<gsup-ie-sm-rp-cause>>|M|TLV|1
|43|SM-RP-UI (diagnostic field)|<<gsup-ie-sm-rp-ui>>|O|TLV|1-...
|===

This message is used to indicate a negative result of an earlier
MO short message delivery. The corresponding MAP service is
MAP-MO-FORWARD-SHORT-MESSAGE, see 3GPP TS 29.002, section 12.2.

==== MO-forwardSM Result

Direction: SMSC (via HLR) => MSC / SGSN

[options="header",cols="5%,45%,20%,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
|40|SM-RP-MR (Message Reference)|<<gsup-ie-sm-rp-mr>>|M|TLV|1
|===

This message is used to indicate a successful result of an earlier
MO short message delivery. The corresponding MAP service is
MAP-MO-FORWARD-SHORT-MESSAGE, see 3GPP TS 29.002, section 12.2.

==== MT-forwardSM Request

Direction: SMSC (via HLR) => MSC / SGSN

[options="header",cols="5%,45%,20%,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
|40|SM-RP-MR (Message Reference)|<<gsup-ie-sm-rp-mr>>|M|TLV|1
|41|SM-RP-DA (Destination Address)|<<gsup-ie-sm-rp-da>>|M|TLV|2-...
|42|SM-RP-OA (Originating Address)|<<gsup-ie-sm-rp-oa>>|M|TLV|2-...
|43|SM-RP-UI (SM TPDU)|<<gsup-ie-sm-rp-ui>>|M|TLV|1-...
|45|SM-RP-MMS (More Messages to Send)|<<gsup-ie-sm-rp-mms>>|O|TLV|1
|===

This message is used to forward MT short messages from an SMSC to MSC / SGSN.
The corresponding MAP service is MAP-MT-FORWARD-SHORT-MESSAGE,
see 3GPP TS 29.002, section 12.9.

==== MT-forwardSM Error

Direction: MSC / SGSN => SMSC (via HLR)

[options="header",cols="5%,45%,20%,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
|40|SM-RP-MR (Message Reference)|<<gsup-ie-sm-rp-mr>>|M|TLV|1
|44|SM-RP-Cause (Cause value)|<<gsup-ie-sm-rp-cause>>|M|TLV|1
|43|SM-RP-UI (diagnostic field)|<<gsup-ie-sm-rp-ui>>|O|TLV|1-...
|===

This message is used to indicate a negative result of an earlier
MT short message delivery. The corresponding MAP service is
MAP-MT-FORWARD-SHORT-MESSAGE, see 3GPP TS 29.002, section 12.9.

==== MT-forwardSM Result

Direction: MSC / SGSN => SMSC (via HLR)

[options="header",cols="5%,45%,20%,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
|40|SM-RP-MR (Message Reference)|<<gsup-ie-sm-rp-mr>>|M|TLV|1
|===

This message is used to indicate a successful result of an earlier
MT short message delivery. The corresponding MAP service is
MAP-MT-FORWARD-SHORT-MESSAGE, see 3GPP TS 29.002, section 12.9.

==== READY-FOR-SM Request

Direction: MSC / SGSN => SMSC (via HLR)

[options="header",cols="5%,45%,20%,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
|40|SM-RP-MR (Message Reference)|<<gsup-ie-sm-rp-mr>>|M|TLV|1
|46|SM Alert Reason|<<gsup-ie-sm-alert-rsn>>|M|TLV|1-...
|===

This message is used between the MSC / SGSN and an SMSC when a subscriber
indicates memory available situation (see TS GSM 04.11, section 7.3.2).
The corresponding MAP service is MAP-READY-FOR-SM,
see 3GPP TS 29.002, section 12.4.

==== READY-FOR-SM Error

Direction: SMSC (via HLR) => MSC / SGSN

[options="header",cols="5%,45%,20%,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
|40|SM-RP-MR (Message Reference)|<<gsup-ie-sm-rp-mr>>|M|TLV|1
|44|SM-RP-Cause (Cause value)|<<gsup-ie-sm-rp-cause>>|M|TLV|1
|43|SM-RP-UI (diagnostic field)|<<gsup-ie-sm-rp-ui>>|O|TLV|1-...
|===

This message is used to indicate a negative result of an earlier
MO SMMA (Memory Available) indication. The corresponding MAP
service is MAP-READY-FOR-SM, see 3GPP TS 29.002, section 12.4.

==== READY-FOR-SM Result

Direction: SMSC (via HLR) => MSC / SGSN

[options="header",cols="5%,45%,20%,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
|40|SM-RP-MR (Message Reference)|<<gsup-ie-sm-rp-mr>>|M|TLV|1
|===

This message is used to indicate a successful result of an earlier
MO SMMA (Memory Available) indication. The corresponding MAP
service is MAP-READY-FOR-SM, see 3GPP TS 29.002, section 12.4.

==== CHECK-IMEI Request

Direction: VLR => EIR (via HLR)

[options="header",cols="5%,45%,20%,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
|50|IMEI|<<gsup-ie-imei>>|M|TLV|11
|===

==== CHECK-IMEI Error

Direction: EIR (via HLR) => VLR

[options="header",cols="5%,45%,20%,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
|===

==== CHECK-IMEI Result

Direction: EIR (via HLR) => VLR

[options="header",cols="5%,45%,20%,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
|51|IMEI Check Result|<<gsup-ie-imei-result>>|M|TLV|3
|===

=== 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
|0x20|Supplementary Service Request
|0x21|Supplementary Service Error
|0x22|Supplementary Service Result
|0x24|MO-forwardSM Request
|0x25|MO-forwardSM Error
|0x26|MO-forwardSM Result
|0x28|MT-forwardSM Request
|0x29|MT-forwardSM Error
|0x2a|MT-forwardSM Result
|0x2c|READY-FOR-SM Request
|0x2d|READY-FOR-SM Error
|0x2e|READY-FOR-SM Result
|0x30|CHECK-IMEI Request
|0x31|CHECK-IMEI Error
|0x32|CHECK-IMEI Result
|===

The category of the message is indicated by the last two bits of the type.
Request, Error and Result messages only differ in these last two bits, so it is
trivial to transform them.

[options="header",cols="20%,80%"]
|===
|Ending Bits|Message Category
|00|Request
|01|Error
|10|Result
|11|Other
|===

[[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|<<gsup-ie-apn>>|C|TLV|3-102
|13|Quality of Service|<<gsup-ie-qos>>|O|TLV|1-20
|14|PDP-Charging Characteristics|<<gsup-ie-charging>>|O|TLV|4
|===

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 14-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|Access Point Name|<<gsup-ie-apn>>
|0x13|QoS|<<gsup-ie-qos>>
|0x14|PDP-Charging Characteristics|<<gsup-ie-charging>>
|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>>
|0x30|Session ID|<<gsup-ie-session-id>>
|0x31|Session State|<<gsup-ie-session-state>>
|0x35|Supplementary Service Info|<<gsup-ie-ss-info>>
|0x40|SM-RP-MR (Message Reference)|<<gsup-ie-sm-rp-mr>>
|0x41|SM-RP-DA (Destination Address)|<<gsup-ie-sm-rp-da>>
|0x42|SM-RP-OA (Originating Address)|<<gsup-ie-sm-rp-oa>>
|0x43|SM-RP-UI (SM TPDU)|<<gsup-ie-sm-rp-ui>>
|0x44|SM-RP-Cause (RP Cause value)|<<gsup-ie-sm-rp-cause>>
|0x45|SM-RP-MMS (More Messages to Send)|<<gsup-ie-sm-rp-mms>>
|0x46|SM Alert Reason|<<gsup-ie-sm-alert-rsn>>
|0x50|IMEI|<<gsup-ie-imei>>
|0x51|IMEI Check Result|<<gsup-ie-imei-result>>
|===

[[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 or VLR 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-apn]]
==== Access Point Name

This encodes the Access Point Name of a PDP Context. The encoding
is defined in 3GPP TS 23.003.

[[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-charging]]
==== PDP-Charging Characteristics

This encodes the ChargingCharacteristics of 3GPP TS 32.215. A HLR may
send this as part of the InsertSubscriberData or within a single PDP
context definition. If the HLR supplies this information it must be
used by the SGSN or VLR when activating a PDP context.

[packetdiag]
----
{
	colwidth = 8
	node_height = 24

	0-3:	Profile Index
	4-15:	Behavior
}
----


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

[[gsup-ie-ss-info]]
==== Supplementary Service Info

This IE shall be used together with both <<gsup-ie-session-state>>
and <<gsup-ie-session-id>> IEs. It is used to carry the payload
of Supplementary Services encoded according to GSM TS 04.80.

=== Session (transaction) management

Unlike TCAP/MAP, GSUP is just a transport layer without the
dialogue/context. All communication is usually happening over
a single connection. In order to fill this gap, there is a few
optional IEs, which allow both communication sides to establish
and terminate TCAP-like transactions over GSUP.

[[gsup-ie-session-id]]
==== Session ID

This auxiliary IE shall be used together with <<gsup-ie-session-state>>.
The purpose of this IE is to identify a particular transaction using
the 4-byte unique identifier.

[[gsup-ie-session-state]]
==== Session State

This auxiliary IE shall be used together with <<gsup-ie-session-id>>.
The purpose of this IE is to indicate a state of a particular
transacrion, i.e. initiate, continue or terminate it.

.Session state
[options="header",cols="15%,35%,50%"]
|===
|State|TCAP alternative|Description
|0x00|Undefined|Used when session management is not required
|0x01|BEGIN|Used to initiate a new session
|0x02|CONTINUE|Used to continue an existing session
|0x03|END|Used to terminate an existing session
|===

[[gsup-ie-sm-rp-mr]]
==== SM-RP-MR (Message Reference)

According to TS GSM 04.11, section 8.2.3, every single message on the
SM-RL (SM Relay Layer) has a unique _message reference_, that is
used to link an _RP-ACK_ or _RP-ERROR_ message to the associated
(preceding) _RP-DATA_ or _RP-SMMA_ message transfer attempt.

In case of TCAP/MAP, this message reference is being mapped to the
_Invoke ID_. But since GSUP has no _Invoke ID IE_, and it is not
required for other applications (other than SMS), a special
<<gsup-ie-sm-rp-mr>> is used to carry the message reference
value \'as-is' (i.e. in range 0 through 255).

[[gsup-ie-sm-rp-da]]
==== SM-RP-DA (Destination Address)

This IE represents the destination address used by the short message service
relay sub-layer protocol. It can be one of the following:

* IMSI (see 3GPP TS 29.002, clause 7.6.2.1);
* MSISDN (see 3GPP TS 29.002, clause 7.6.2.17);
* service centre address (see 3GPP TS 29.002, clause 7.6.2.27).

Coding of this IE is described in <<gsup-sm-rp-oda>>.
See 3GPP TS 29.002, section 7.6.8.1 for details.

[[gsup-ie-sm-rp-oa]]
==== SM-RP-OA (Originating Address)

This IE represents the originating address used by the short message service
relay sub-layer protocol. It can be either of the following:

* MSISDN (see 3GPP TS 29.002, clause 7.6.2.17);
* service centre address (see 3GPP TS 29.002, clause 7.6.2.27).

Coding of this IE is described in <<gsup-sm-rp-oda>>.
See 3GPP TS 29.002, section 7.6.8.2 for details.

[[gsup-sm-rp-oda]]
==== Coding of SM-RP-DA / SM-RP-OA IEs

Basically, both <<gsup-ie-sm-rp-da>> / <<gsup-ie-sm-rp-oa>> IEs
contain a single TV of the following format:

.Coding of SM-RP-DA / SM-RP-OA IEs
[options="header",cols="5%,5%,10%,80%"]
|===
|Field|Presence|Length|Description
|T|M|1|Identity type
|V|O|...|Encoded identity itself
|===

where the identity type can be one of the following:

.Identity types of SM-RP-DA / SM-RP-OA IEs
[options="header",cols="15%,85%"]
|===
|Type|Description
|0x01|IMSI (see 3GPP TS 29.002, clause 7.6.2.1)
|0x02|MSISDN (see 3GPP TS 29.002, clause 7.6.2.17)
|0x03|Service centre address (see 3GPP TS 29.002, clause 7.6.2.27)
|0xff|Omit value for noSM-RP-DA and noSM-RP-OA
|===

[[gsup-ie-sm-rp-ui]]
==== SM-RP-UI (SM TPDU)

This IE represents the user data field carried by the short message service
relay sub-layer (i.e. SM-TL (Transfer Layer)) protocol. In case of errors
(i.e. MO-/MT-forwardSM Error messages), this IE may contain optional
diagnostic field payload from _RP-ERROR_ message.

See 3GPP TS 29.002, section 7.6.8.4 for details.

[[gsup-ie-sm-rp-cause]]
==== SM-RP-Cause (RP Cause value)

According to TS GSM 04.11, _RP-Cause_ is a variable length element always
included in the _RP-ERROR_ message, conveying a negative result of an
_RP-DATA_ message transfer attempt or _RP-SMMA_ notification attempt.

The mapping between error causes in TS GSM 04.11 and TS GSM 09.02 (MAP)
is specified in TS GSM 03.40. But since GSUP has no generic _User Error IE_,
and it is not required for other applications (other than SMS), a special
<<gsup-ie-sm-rp-cause>> is used to carry the cause value \'as-is'.

[[gsup-ie-sm-rp-mms]]
==== SM-RP-MMS (More Messages to Send)

This is an optional IE of MT-ForwardSM-Req message, that is used by SMSC
to indicate that there are more MT SMS messages to be sent, so the network
should keep the RAN connection open. See 3GPP TS 29.002, section 7.6.8.7.

[[gsup-ie-sm-alert-rsn]]
==== SM Alert Reason

According to 3GPP TS 29.002, section 7.6.8.8, Alert Reason is used to
indicate the reason why the service centre is alerted, e.g. the MS has
got some memory to store previously rejected incoming SMS.

It can take one of the following values:

.SM Alert Reason values
[options="header",cols="15%,85%"]
|===
|Type|Description
|0x01|MS present
|0x02|Memory Available
|===

[[gsup-ie-imei]]
==== IMEI

The IMEI encoded as Called Party BCD Number in 3GPP TS 04.08.

[[gsup-ie-imei-result]]
==== IMEI Check Result

Result of the Check IMEI request. A NACK could be sent in theory, if the ME is
not permitted on the network (e.g. because it is on a blacklist).

.IMEI Check Result
[options="header",cols="10%,90%"]
|===
|Type|Description
|0x01|ACK
|0x02|NACK
|===