NGAP Protocol

[boardslayer]

Hello, Is it possible to add NGAP protocol support to the kit? It is mainly used in 5G Networks. How would one go about adding support for it?
TIA

[JarryShaw]

Yes, it would be pretty much welcomed if you could add the protocol support yourself.

To do this, I would suppose this is an application layer protocol, you need to create a skeleton class that represents the protocol itself, a data class that holds the protocol header fields, and a schema class that defines the structure of the protocol.

Schema Class

from pcapkit.corekit.fields.numbers import UInt32Field
from pcapkit.corekit.fields.strings import BytesField
from pcapkit.protocols.schema.schema import Schema, schema_final


@schema_final  # this will automatically generate a constructor for this class
class Schema_NGAP(Schema):
	# now you define the fields in order, for example, we say it has firstly two ports then binary data
	port_one = UInt32Field()
	port_two = UInt32Field()
	data = BytesField(lambda: pkt: pkt['__length__'])

for more information on the pkt lambda used in the field definitions, please see the Schema class's documentation

Data Class

from pcapkit.corekit.infoclass import info_final
from pcapkit.protocols.data.protocol import Protocol


@info_final
class Data_NGAP(Protocol):
	port_one: int
	port_two: int
	data: bytes

Skeleton Class

from pcapkit.protocols.application.application import Application
from pcapkit.utilities.exceptions import ProtocolError, UnsupportedCall


class NGAP(Application[Data_GNAP, Schema_NGAP], data=Data_NGAP, schema=Schema_NGAP):

	@property
	def name(self):
		return 'NG Application Protocol'

	def read(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_NGAP':
		if length is None:
			length = len(self)
		schema = self.__header__

		# extra handling of data mapping/processing can be done here before storing to the data class
		return Data_NGAP(port_one=schema.port_one, port_two=schema.port_two, data=schema.data)

	def make(...) -> Schema_NGAP':  # constructor for the protocol with given args
 		...
		return Schema_NGAP(port_one=..., port_two=..., data=...)

Protocol Registration

If this protocol is wrapped under TCP (or UDP is the same), then you can register it by calling the register method:

from pcapkit.protocols.transport.tcp import TCP

TCP.register(port_number, NGAP)

[JarryShaw]

The prerequisite for this is now in place, so an implementation has somewhere to plug in.

SCTP landed in #379 as a first-class transport protocol per RFC 9260 — common header, all thirteen chunk types, chunk parameters, error causes, CRC32c verification. That matters here because NGAP runs over SCTP, and the next layer is dispatched on the DATA chunk's payload protocol identifier, which is exactly the seam NGAP needs.

Concretely, what already exists:

• The PPID enum values. PayloadProtocolIdentifier_3GPP_NG_Application_Protocol = 60, and = 66 for NGAP over DTLS over SCTP, both in pcapkit.const.sctp.payload_protocol_identifier.

• The dispatch hook. register_sctp(code, module) in pcapkit.foundation.registry.protocols, keyed on that identifier. So registration is a one-liner once a protocol class exists:

  from pcapkit.foundation.registry import register_sctp
  register_sctp(60, NGAP)

• Note register_apptype() deliberately does not fan out to SCTP, since SCTP dispatches on PPID rather than on port numbers.

What does not exist yet is NGAP itself — there is no protocol class anywhere in the tree, and no stub. So this remains open, and the walkthrough written earlier in this thread is still the guide for doing it: schema, data model, protocol skeleton, registration.

One practical caveat for anyone picking it up: NGAP is ASN.1 PER-encoded (3GPP TS 38.413), which is a different shape of problem from the bit-and-octet field parsing the rest of pcapkit does. Worth deciding early whether to lean on an external ASN.1 decoder or to hand-roll the subset needed, because that choice shapes the schema.

Also relevant if you go looking at how SCTP does things: the pcapkit.corekit.context channel added for ESP in #378 gives a protocol-keyed way to pass caller-supplied state down the parse, which is the mechanism to reuse if NGAP ever needs configuration handed in from outside.

[JarryShaw]

One more thing now recorded, since this is where anyone tracking NGAP would look for it: PPID 66, NGAP over DTLS over SCTP, is blocked on DTLS rather than on NGAP.

pcapkit has no DTLS dissector, and no stub for one anywhere in the tree — only TLS/SSL has a stub. So even with an NGAP class registered on PPID 66, the bytes handed to it are a DTLS record rather than an NGAP PDU, and can only degrade to Raw. PPID 60 (NGAP directly over SCTP) is unaffected; it is 66 through 69 — NGAP, XnAP, F1AP and E1AP over DTLS — that need the record layer first. The same applies to PPID 47, Diameter over DTLS/SCTP, and to the SCTP DTLS chunk (type 65) and its key-management parameter and error causes, all of which are registered in the enums and parse as opaque.

A DTLS record-layer dissector is enough to unblock it: content type, version, epoch, sequence number, length, and the fragment offset and length DTLS adds to handshake messages. Decryption is a separate question and is not needed to make the records legible, in the same way ESP parses without keys.

Two other things worth knowing for an NGAP implementation, from the same audit:

• There is no SCTP reassembly, so a PDU split across DATA chunks will not decode. The B and E fragment bits are parsed and reported but nothing reads them, and each fragment is dispatched on its own PPID as though it were a whole PDU. Recorded as its own topic in PyPCAPKit Enhancement Proposals #106.
• Only the first DATA chunk of a bundle is dispatched. A packet bundling several DATA chunks records them all in the chunk list, but the next layer runs on the first one only.

Both are now on the Help Wanted page — DTLS under its own heading, and reassembly under "Reassembly Beyond IP and TCP".