1
0
Fork 0
gsmtapv3/GSMTAPv3.md

11 KiB

This is the draft GSMTAPv3 specification. Please note that this is not yet finalized standard, and changes are expected.

Global header structure

struct gsmtap_hdr_v3 {
	uint8_t version;
	uint8_t res;
	uint16_t hdr_len;

	uint16_t type;
	uint16_t sub_type;

	uint8_t metadata[0];
};

Version: 1 octet integer representing the GSMTAP version number, currently 1, 2, and 3. Res: Reserved for future use. Must be initialized with 0.

Header length: 2 octet integer representing the length of GSMTAP header in number of 32-bit words. The header length includes the length of both global header and type-specific metadata. Any data beyond this header length are expected to be interpreted as the payload. The minimum header length value is 2. If header length value is smaller than 2, then the GSMTAP data is considered invalid.

If the header length indicated in the header is longer than the length specified by the transport layer protocol, then the GSMTAP data is considered invalid.

Type: 2 octet integer representing the type of the data.

Sub-type: 2 octet integer representing the specific type of the data among the same type.

Metadata: All metadata are expected to be in T16L16V format. Depending on the type of the data, a set of metadata may be defined as mandatory to properly and unambiguously decode the payload.

Types

The first octet represents the type's category. All available types are grouped by the first octet.

0x00, 0x01: Common and non-3GPP protocols

0x0000: GSMTAPV3_TYPE_OSMOCORE_LOG

libosmocore logging data, as defined in the GSMTAPv2 structure.

0x0001: GSMTAPV3_TYPE_SIM

ISO 7816 smartcard interface.

The payload could be one of the following: complete APDU, TPDU, PPS, card ATR. Each subtype indicates the payload's type.

0x0002: GSMTAPV3_TYPE_BASEBAND_DIAG

Baseband diagnostic data.

The subtype indicates which baseband manufacturer generated the specific data frame. The payload is expected to be each data unit in the diagnostic data stream, i.e. everything between data start and end marker. The payload is expected to be completely unescaped, i.e. it should not contain PPP byte stuffing (using 0x7D 0x5D to represent 0x7D).

0x0003: GSMTAPV3_TYPE_SIGNAL_STATUS_REPORT

Radio signal status report for applications requiring asynchronous status report.

Base stations have synchronous signal status report for each transmitted/received frame, while user equipments can have an independent signal status report aside from each received frame. This type is used for recording an independent signal status report, not attached to any other data types.

0x0004: GSMTAPV3_TYPE_TETRA_I1

TETRA I1 air interface.

0x0005: GSMTAPV3_TYPE_TETRA_I1_BURST

0x0006: GSMTAPV3_TYPE_GMR1_UM

GMR1 layer 2 packets.

0x0007: GSMTAPV3_TYPE_E1T1

E1/T1 lines.

0x0008: GSMTAPV3_TYPE_WMX_BURST

WiMAX burst.

TBD: deprecation of this type? There are no free software WiMAX network implementation and commercial networks are either shutting down or switching to LTE(-TDD).

0x02: GSM

0x0200: GSMTAPV3_TYPE_UM

GSM Um air interface

0x0201: GSMTAPV3_TYPE_UM_BURST

Raw burst bits of Um air interface

0x0202: GSMTAPV3_TYPE_GB_RLCMAC

GPRS Gb interface: RLC/MAC

0x0203: GSMTAPV3_TYPE_GB_LLC

GPRS Gb interface: LLC

0x0204: GSMTAPV3_TYPE_GB_SNDCP

GPRS Gb interface: SNDCP

0x0205: GSMTAPV3_TYPE_ABIS

0x0206: GSMTAPV3_TYPE_RLP

GSM RLP frames, as per 3GPP TS 24.022.

0x03: UMTS/WCDMA

0x0300: GSMTAPV3_TYPE_UMTS_MAC

UMTS MAC PDU with context, as per 3GPP TS 25.321.

0x0301: GSMTAPV3_TYPE_UMTS_RLC

UMTS RLC PDU with context, as per 3GPP TS 25.322.

The payload is expected to be encoded in the RLC PDU format defined in the Section 9 "Elements for peer-to-peer communication". The data transfer mode as defined in the Table 9.1 "RLC PDU names and descriptions" (TM, UM, AM) must be defined in order to properly decode the RLC PDU.

A ciphering protection key CK could be optionally provided through the metadata for deciphering in AM/UM transport.

0x0302: GSMTAPV3_TYPE_UMTS_PDCP

UMTS PDCP PDU with context, as per 3GPP TS 25.323.

0x0303: GSMTAPV3_TYPE_UMTS_RRC

UMTS RRC PDU, as per 3GPP TS 25.331.

The payload is expected to be encoded in the ASN.1 unaligned PER format. The subtype numbers are defined according to the messages definitions of the 3GPP TS 25.331 Version 17.0.0, Sections 11.1 "General message structure". For compatibility reason, when the first octet is 0x01, the second octet indicates a specific PDU type instead of a specific channel.

An integrity protection key IK could be optionally provided through the metadata for integrity checking.

0x04: LTE

0x0400: GSMTAPV3_TYPE_LTE_MAC

LTE MAC PDU with context, as per 3GPP TS 36.321.

0x0401: GSMTAPV3_TYPE_LTE_RLC

LTE RLC PDU with context, as per 3GPP TS 36.322.

The payload is expected to be encoded in the RLC PDU format defined in the Section 6 "Protocol data units, formats and parameters". The data transfer mode (TM, UM, AM) and the SN length (5/10 bits for UM, 10/16 bits for AM) must be defined in order to properly decode the RLC PDU.

0x0402: GSMTAPV3_TYPE_LTE_PDCP

LTE PDCP PDU with context, as per 3GPP TS 36.323.

Integrity protection and ciphering key for control plane (K_RRCint, K_RRCenc) and user plane (only K_UPenc; no user plane integrity protection) could be optionally provided through the metadata.

0x0403: GSMTAPV3_TYPE_LTE_RRC

LTE RRC PDU, as per 3GPP TS 36.331.

The payload is expected to be encoded in the ASN.1 unaligned PER format. The subtype numbers are defined according to the messages definitions of the 3GPP TS 36.331 Version 17.0.0, Sections 6.2 "RRC messages", 6.5 "PC5 RRC messages", and 6.7 "NB-IoT RRC messages". Note that RRC messages, PC5 RRC messages, and NB-IoT RRC messages have different first octet in the subtype. If a further 3GPP release adds additional channels, new channels included in the later revision should be added after the original definition in order to maintain the backwards compatibility.

0x0404: GSMTAPV3_TYPE_NAS_EPS

EPS Non-Access Stratum, as per 3GPP TS 24.301.

The payload is expected to be encoded in the layer 3 signalling message format. The subtype numbers indicate whether the NAS payload is ciphered or not. If the payload is ciphered, K_NASint and K_NASenc is optionally available through the metadata for deciphering and integrity checking.

0x05: NR

0x0500: GSMTAPV3_TYPE_NR_MAC

NR MAC PDU with context, as per 3GPP TS 38.321.

0x0501: GSMTAPV3_TYPE_NR_RLC

NR RLC PDU with context, as per 3GPP TS 38.322.

The payload is expected to be encoded in the RLC PDU format defined in the Section 6 "Protocol data units, formats and parameters". The data transfer mode (TM, UM, AM) and the SN length (6/12 bits for UM, 12/18 bits for AM) must be defined in order to properly decode the RLC PDU.

0x0502: GSMTAPV3_TYPE_NR_PDCP

NR PDCP PDU with context, as per 3GPP TS 38.323.

Integrity protection and ciphering key for control plane (K_RRCint, K_RRCenc) and user plane (K_UPint, K_UPenc) could be optionally provided through the metadata.

0x0503: GSMTAPV3_TYPE_NR_RRC

NR RRC PDU, as per 3GPP TS 38.331.

The payload is expected to be encoded in the ASN.1 unaligned PER format. The subtype numbers are defined according to the messages definitions of the 3GPP TS 38.331 Version 17.0.0, Sections 6.2 "RRC messages" and 6.5 "PC5 RRC messages". Note that RRC messages and PC5 RRC messages have different first octet in the subtype. If a further 3GPP release adds additional channels, new channels included in the later revision should be added after the original definition in order to maintain the backwards compatibility.

0x0504: GSMTAPV3_TYPE_NAS_5GS

5GS Non-Access Stratum, as per 3GPP TS 24.501.

The payload is expected to be encoded in the layer 3 signalling message format. The subtype numbers indicate whether the NAS payload is ciphered or not. If the payload is ciphered, K_NASint and K_NASenc is optionally available through the metadata for deciphering and integrity checking.

Metadata

Anything in this section is considered as TBD.

Additional context information

Packet timestamp

Packet timestamp metadata could be added, if the data generation entity keeps its own clock.

Following formats are available:

  • Length 8: Unsigned 64-bit integer containing the current UNIX time in seconds
  • Length 12: In addition to 64-bit timestamp, unsigned 32-bit integer containing miliseconds
  • Length 16: In addition to 64-bit timestamp, unsigned 64-bit integer containing nanoseconds

Packet comment

Freetext comment of the specific GSMTAP packet in UTF-8 encoded format.

Network frequency and cell information

Channel number

Unsigned 32-bit integer, containing one of the following value:

  • ARFCN, as defined in 3GPP TS 45.005, Section 2 "Frequency bands and channel arrangement"
  • UARFCN, as defined in the 3GPP TS 25.101, Section 5.4 "Channel arrangement" and 3GPP TS 25.102, Section 5.4 "Channel arrangement"
  • EARFCN, as defined in the 3GPP TS 36.101, Section 5.7.3 "Carrier frequency and EARFCN"
  • NR-ARFCN, as defined in the 3GPP TS 38.104, Section 5.4 "Channel arrangement"
  • TETRA channel number

The exact type of channel number depends on the payload type.

For UARFCN, EARFCN, and NR-ARFCN an unsigned 16-bit integer is defined to indicate the frequency band.

For GSM, band indicator may be omitted as there are no overlapping ARFCNs among frequently used GSM frequency bands including 450, 480, 900/1800, and 850/1900 (see Table 2-2 of TS 45.005), and whether the cell is 850/1900 or 900/1800 is included in SI3/SI6. Nevertheless, these values could be specified:

  • GSM 900 (P/E/R/ER)
  • DCS 1800
  • PCS 1900
  • GSM 450
  • GSM 480
  • GSM 850
  • T-GSM 380
  • T-GSM 410
  • T-GSM 810
  • GSM 710
  • GSM 750

For TETRA, band indicator could be one of 0b0011, 0b0100, 0b1001.

Frequency

Cell's frequency in Hz.

Following formats are available:

  • Length 4: Unsigned 32-bit integer containing the Hz value
  • Length 8: Unsigned 64-bit integer containing the Hz value

Multiplexing information

One of the following:

  • GSM: BSIC
  • UMTS/WCDMA: PSC
  • LTE: PCI
  • NR: PCI

Timing

  • GSM: timeslot, subslot, frame number
  • UMTS/WCDMA: system frame number
  • LTE: hyper frame number (only for NB-IoT), system frame number, subframe number
  • NR: system frame number, subframe number
  • TETRA: hyper frame number, symbol number, timeslot number, frame number, multiframe number

Ciphering and integrity protection key

Separate tags for K_NASint, K_NASenc, K_RRCint, K_RRCenc, K_UPint, K_UPenc should be provided.

Once the key had been provided, the key is considered valid unless the generation changes (e.g. K_NAS provided for NAS-EPS is considered valid until NAS-5GS or Abis packet comes) or a new key has been provided.

Signal status