NGAP - NG Application Protocol

pcapkit.protocols.application.ngap contains NGAP only, which implements extractor for the NG Application Protocol (NGAP) [*], as specified in 3GPP TS 38.413.

NGAP is the control plane between a 5G RAN node (gNB or ng-eNB) and an AMF. It runs over SCTP and is named by the DATA chunk’s payload protocol identifier rather than by a port, so NGAP is registered on SCTP.__proto__ under PPID 60 (NG_Application_Protocol) and PPID 66 (NGAP_over_DTLS_over_SCTP), c.f. pcapkit.foundation.registry.protocols.register_sctp().

An SCTP DATA chunk that names NGAP carries exactly one NGAP-PDU, encoded in aligned PER (ALIGNED PACKED ENCODING RULES, APER). There is no header to read and no framing to resolve: the whole payload is the encoding, and none of its structure is visible until an ASN.1 decoder has run over it.

Decoding therefore needs the optional pycrate dependency (pip install pypcapkit[NGAP]). pcapkit imports and works without it; an NGAP payload simply degrades to the opaque payload path, exactly as an unregistered PPID would, because SCTP._import_next_layer is wrapped in beholder() and falls back to Raw.

Why pycrate rather than a PER codec of our own

Two things make it the cheaper answer. pycrate ships NGAP already compiled, at pycrate_asn1dir/NGAP.py, so the 3GPP ASN.1 source does not have to be vendored here and tracked across releases; and it is pure Python, with no compiled extension to build on any platform. Decoding costs 0.15 ms per PDU, the same order as pcapkit’s own per-packet cost, so the generic strategy below is not paying for the convenience.

Generic conversion, not 81 hand-written procedures

The decoded value tree is mapped into Info objects structurally, by ASN.1 shape rather than by procedure:

ASN.1 / pycrate shape

pcapkit model

SEQUENCE / SET (a dict)

Sequence

SEQUENCE OF (a list)

list

CHOICE / open type

Choice

BIT STRING

BitString

INTEGER, OCTET STRING,

kept as int, bytes, str

ENUMERATED, BOOLEAN

That is a deliberate trade. Every one of the 81 elementary procedures and 438 protocol IEs works on the day it is decoded, and a new 3GPP release needs no code change here; what is given up is per-IE typing, so an IE’s value is reported in the specification’s own shape rather than as a pcapkit-specific model. The fields worth reading at a glance – the PDU kind, procedure code, criticality, message type name and the IE list – are surfaced as first-class fields on NGAP regardless.

Known limitations

  • PPID 66 payloads are not decoded. NGAP_over_DTLS_over_SCTP wraps the NGAP-PDU in a DTLS record, and pcapkit implements no DTLS, so the bytes reaching NGAP.read() are not an APER encoding. The PPID is registered so that it is named rather than anonymous; the payload itself degrades to Raw.

  • The specification version is |pycrate|_’s, not this package’s. The IE and procedure enumerations were generated from NGAP_Constants of pycrate 0.8.1 (Release-18-era: 81 procedure codes, 438 protocol IE IDs, highest 443). A pycrate that carries a newer NGAP will decode IEs that ProcedureCode and ProtocolIE do not name; both extend themselves at lookup time rather than failing, so such a value is reported as Unassigned_<n>.

  • NGAP over a fragmented SCTP association is not reassembled. A DATA chunk is decoded on its own, so an NGAP-PDU split across chunks by SCTP fragmentation fails to decode rather than being reassembled first.

  • Private IEs (``PrivateMessage``) carry no schema. Their contents are vendor defined, so the generic conversion reports whatever ASN.1 shape the encoding declares and cannot name the fields.

class pcapkit.protocols.application.ngap.NGAP(file=None, length=None, **kwargs)[source]

Bases: Application[NGAP, NGAP]

This class implements NG Application Protocol.

property name: Literal['NG Application Protocol']

Name of current protocol.

property length: int

Header length of current protocol.

NGAP prefixes its payload with nothing and carries no next layer, so the whole NGAP-PDU is the header and this is its length. That is not self.__length_hint__, which reports the four-octet prefix common to every PDU rather than this PDU’s size.

read(length=None, **kwargs)[source]

Read NG Application Protocol (NGAP).

Parameters:

  • length (int | None) – Length of packet data.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

NGAP

Returns:

Parsed packet data.

Raises:

ProtocolError – If pycrate is not installed, or if the payload is not a well formed aligned PER NGAP-PDU.

make(kind=PDUKind.INITIATING_MESSAGE, procedure=None, criticality=<Criticality.reject: 0>, message=None, value=None, data=None, **kwargs)[source]

Make (construct) packet data.

Parameters:

  • kind (PDUKind | str) – Which NGAP-PDU alternative to construct.

  • procedure (ProcedureCode | int | None) – Procedure code.

  • criticality (Criticality | int | str) – Criticality of the procedure.

  • message (str | None) – Name of the message type, e.g. NGSetupRequest.

  • value (Any) – Message body, either as Sequence from a previous read() or as the plain Python value pycrate expects.

  • data (bytes | None) – Pre-encoded NGAP-PDU. When given, it is used verbatim and every other argument is ignored, which is also the only path that does not need pycrate.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type:

NGAP

Returns:

Constructed packet data.

Raises:

ProtocolError – If data is not given and either procedure or message is missing, if pycrate is not installed, or if the arguments do not describe a message the specification can encode.

__length_hint__()[source]

Return an estimated length for the object.

Every NGAP-PDU opens with the same four octets under aligned PER – the CHOICE index, the procedure code, the criticality, and the first octet of the open type’s length determinant – so four is the fixed prefix NGAP has in place of a header. It is not a minimum PDU length: the smallest complete NGAP-PDU measured here, a message whose protocolIEs list is empty, is seven octets.

Return type:

Literal[4]

classmethod _make_data(data)[source]

Create key-value pairs from data for protocol construction.

Parameters:

data (NGAP) – protocol data

Return type:

dict[str, Any]

Returns:

Key-value pairs for protocol construction.

Auxiliary Functions

pcapkit.protocols.application.ngap.load_pycrate()[source]

Load the optional pycrate NGAP-PDU object.

Return type:

Any | None

Returns:

pycrate_asn1dir.NGAP.NGAP_PDU_Descriptions.NGAP_PDU, the CHOICE over initiatingMessage / successfulOutcome / unsuccessfulOutcome that is the entry point of the compiled specification, or None when pycrate is not installed.

Notes

The import is attempted at most once and the outcome is cached. It is not free even when it succeeds – pycrate_asn1dir.NGAP is a 4.9 MB module – which is the other reason it happens here rather than at module import: neither import pcapkit nor the documentation build should pay for it.

pcapkit.protocols.application.ngap._PYCRATE: Any = NotImplemented

Cached NGAP-PDU object, c.f. load_pycrate(). NotImplemented means the import has not been attempted yet, and None that it was attempted and pycrate is not installed – three states, so a capture full of NGAP packets does not pay for a failing import on every frame.

pcapkit.protocols.application.ngap._PDU_LOCK

Guards the module-level NGAP-PDU object returned by load_pycrate(). That object is stateful: from_aper() stores the decoded value on it and get_val() hands back the decoder’s own containers rather than copies, so two decodes running concurrently through it would each see the other’s tree. The lock is held across the conversion, not merely across the decode, for that second reason.

pcapkit.protocols.application.ngap._convert(value)[source]

Convert a pycrate decoded value into pcapkit data models.

Parameters:

value (Any) – A node of the tree returned by NGAP_PDU.get_val().

Return type:

Any

Returns:

The same tree, with mappings as Sequence, CHOICE pairs as Choice, and BIT STRING pairs as BitString.

Notes

The two 2-tuple shapes are told apart by their first element, which is unambiguous: pycrate spells a CHOICE as (name, value) with a str name and a BIT STRING as (bits, length) with two int. Any other tuple is passed through with its members converted, so an ASN.1 construct not listed above degrades to its own shape rather than being mangled into one of these.

pcapkit.protocols.application.ngap._revert(value)[source]

Convert pcapkit data models back into a pycrate value.

Parameters:

value (Any) – A node of a tree produced by _convert(), or the equivalent plain Python value.

Return type:

Any

Returns:

The same tree in the shape NGAP_PDU.set_val() expects.

Notes

Choice and BitString are tested before Info, since they are subclasses of it and would otherwise be reverted to mappings.

Auxiliary Data

class pcapkit.protocols.application.ngap.PDUKind(*values)[source]

Bases: StrEnum

Which alternative of the NGAP-PDU CHOICE a PDU is.

The values are spelled as the ASN.1 identifiers, so that a name decoded by pycrate resolves by value.

INITIATING_MESSAGE = 'initiatingMessage'

A procedure’s request, or a class 2 procedure’s only message.

SUCCESSFUL_OUTCOME = 'successfulOutcome'

A class 1 procedure’s successful response.

UNSUCCESSFUL_OUTCOME = 'unsuccessfulOutcome'

A class 1 procedure’s unsuccessful response.

static _generate_next_value_(name, start, count, last_values)

Return the lower-cased version of the member name.

class pcapkit.protocols.application.ngap.Criticality(*values)[source]

Bases: IntEnum

[Criticality] What a receiver must do with an IE it does not understand.

Members are named for the ASN.1 identifiers rather than upper-cased, so that Criticality.get() resolves a name decoded by pycrate through the standard member map. The values are the ENUMERATED indices, which is what goes on the wire.

reject = 0

Reject the whole message.

ignore = 1

Ignore the IE and carry on.

notify = 2

Ignore the IE, carry on, and report it.

classmethod _missing_(value)[source]

Lookup function used when value is not found.

Parameters:

value (int) – Value to get enum item.

Raises:

ValueError – Always. Criticality is an ENUMERATED with no extension marker, so a fourth value cannot be encoded and a lookup for one is a bug rather than a newer specification.

Return type:

NoReturn

class pcapkit.protocols.application.ngap.ProcedureCode(*values)[source]

Bases: IntEnum

[ProcedureCode] NGAP elementary procedure codes, 3GPP TS 38.413.

class pcapkit.protocols.application.ngap.ProtocolIE(*values)[source]

Bases: IntEnum

[ProtocolIE-ID] NGAP protocol IE identifiers, 3GPP TS 38.413.

An IE’s ID name and the name of the open type its value is keyed under differ in places – IE 21 is id-DefaultPagingDRX but its value arrives keyed PagingDRX – so IE.type carries the latter alongside this.

Note

ProcedureCode and ProtocolIE are rendered without their members on purpose: between them they carry 519 of them, each named for the 3GPP identifier it comes from, and a page listing all of them is longer than the specification’s own tables and no more useful. Read them from pcapkit/protocols/application/ngap.py, or from pycrate_asn1dir.NGAP.NGAP_Constants, which is where they were generated from.

Unlike the enumerations under pcapkit.const, these are not crawled from an IANA registry – 3GPP publishes them in the ASN.1 of TS 38.413 rather than in a registry with a stable page – so there is no matching module under pcapkit.vendor.

Header Schemas

class pcapkit.protocols.schema.application.ngap.NGAP(dict_=None, **kwargs)[source]

Bases: Schema

Header schema for NGAP packet.

NGAP has no header of its own: an SCTP DATA chunk whose payload protocol identifier names NGAP carries exactly one aligned-PER-encoded NGAP-PDU and nothing else, so there is no length field to read and no framing to resolve. The whole payload is the encoding, and its structure only becomes visible once the ASN.1 decoder has run.

data: bytes = <BytesField data>

Aligned PER encoding of one NGAP-PDU.

Data Models

class pcapkit.protocols.data.application.ngap.NGAP(*args: VT, **kwargs: VT)[source]

Bases: Protocol

Data model for NGAP protocol.

The three NGAP-PDU alternatives – initiatingMessage, successfulOutcome and unsuccessfulOutcome – carry an identical field set and are distinguished by kind rather than by three near-identical models.

kind: PDUKind

Which of the three NGAP-PDU alternatives this is.

procedure: ProcedureCode

Procedure code.

criticality: Criticality

Criticality of the procedure.

message: str

Name of the message type, e.g. NGSetupRequest.

ies: tuple[IE, ...]

Protocol IEs of the message, in the order they were encoded. Empty for the few messages that carry no protocolIEs field.

value: Sequence

The message body, converted in full. ies is a flattened view of its protocolIEs field, so anything not surfaced above is reachable here.

class pcapkit.protocols.data.application.ngap.IE(*args: VT, **kwargs: VT)[source]

Bases: Data

Data model for one NGAP protocol information element.

id: ProtocolIE

Protocol IE ID.

criticality: Criticality

Criticality, i.e. what a receiver must do when it does not understand id.

type: str

Name of the IE’s open type, as spelled in 3GPP TS 38.413. This is not always id’s own spelling – IE 21 is id-DefaultPagingDRX but its value is keyed PagingDRX.

value: Any

Value of the IE.

class pcapkit.protocols.data.application.ngap.Choice(*args: VT, **kwargs: VT)[source]

Bases: Data

Data model for an ASN.1 CHOICE alternative or open type.

Both the selected alternative’s name and its value are kept, since the name is the only thing that says which of the alternatives was sent – an NGAP-PDU carrying ('globalGNB-ID', ...) and one carrying ('globalNgENB-ID', ...) are otherwise indistinguishable once the value has been converted.

name: str

Name of the selected alternative, as spelled in 3GPP TS 38.413.

value: Any

Value of the selected alternative.

class pcapkit.protocols.data.application.ngap.BitString(*args: VT, **kwargs: VT)[source]

Bases: Data

Data model for an ASN.1 BIT STRING.

A bit string is not a whole number of octets, so its length is carried alongside its value rather than being implied by it – gNB-ID is a 22-to-32-bit field, and (0x000102, 24) and (0x000102, 32) are different identifiers.

value: int

Bits, as a big-endian unsigned integer.

length: int

Number of significant bits in value.

class pcapkit.protocols.data.application.ngap.Sequence(*args: VT, **kwargs: VT)[source]

Bases: Data

Data model for an ASN.1 SEQUENCE, SET or SEQUENCE OF member.

Fields are whatever the specification names them, so this model carries no fixed annotations: it is populated from the decoded value tree. ASN.1 identifiers are hyphenated where Python identifiers cannot be, e.g. gNB-ID, so such fields are reachable by subscription (seq['gNB-ID']) rather than by attribute access.

Footnotes