UDP - User Datagram Protocol¶

pcapkit.protocols.transport.udp.protocol contains UDP only, which implements the extractor for User Datagram Protocol (UDP) [*], whose structure is:

Octets	Bits	Name	Description
0	0	`udp.srcport`	Source Port
2	16	`udp.dstport`	Destination Port
4	32	`udp.len`	Length (header included)
6	48	`udp.checksum`	Checksum

class pcapkit.protocols.transport.udp.protocol.UDP(file=None, length=None, **kwargs)[source]¶

Bases: Transport[UDP, UDP]

This class implements User Datagram Protocol.

The self.__proto__ registry binds these ports:

Port Number	Protocol
80	`pcapkit.protocols.application.http.protocol.HTTP`
1701	`pcapkit.protocols.link.l2tpv2.protocol.L2TPv2`
5684	`pcapkit.protocols.application.dtls.protocol.DTLS`
8080	`pcapkit.protocols.application.http.protocol.HTTP`

Note

HTTP, bound as in TCP.__proto__, picks HTTPv1 or HTTPv2 from the payload through _dispatch_version().

Changed in version 1.5.0: make() takes total_length, which a from_data() rebuild passes so that a truncated capture keeps its declared Length (#1155), and trailer, so that the octets past the Length field rebuild as captured (#1461).

Changed in version 1.6.0:

Port 5684 binds DTLS (#2437).
The checksum is computed when make() is given none, over the pseudo it is given or by the enclosing IP layer, and verified by that layer under CHECKSUM_VERIFY (#2474).
make() raises ProtocolError for a Length past 16 bits, given or computed, and a checksum that is not two octets, where it wrote the Length’s low 16 bits and padded or cut the checksum (#2614).

__proto__: DefaultDict[int, ModuleDescriptor[ProtocolBase] | Type[ProtocolBase]]¶: Protocol index mapping for decoding next layer, see self._decode_next_layer & self._import_next_layer.

__proto_key__: ClassVar[tuple[Type[EnumRegistry], bool]]¶: What __proto__ is keyed by – the enum a key must be a member of, and whether a bare int is valid too. Read by register_protocol_code() to check a code= key as register_udp() checks its own; a bare int is a port number, which an AppType member carries (#2268).

property name: Literal['User Datagram Protocol']¶: Name of current protocol.

property length: Literal[8]¶: Header length of current protocol.

property src: AppType¶: Source port.

property dst: AppType¶: Destination port.

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

Read User Datagram Protocol (UDP).

Structure of UDP header [RFC 768]:

 0      7 8     15 16    23 24    31
+--------+--------+--------+--------+
|     Source      |   Destination   |
|      Port       |      Port       |
+--------+--------+--------+--------+
|                 |                 |
|     Length      |    Checksum     |
+--------+--------+--------+--------+
|
|          data octets ...
+---------------- ...

Parameters:

length (int | None) – Length of packet data.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

UDP

Returns:

Parsed packet data.

make(srcport=0, dstport=0, checksum=None, total_length=None, payload=b'', trailer=b'', pseudo=None, **kwargs)[source]¶

Make (construct) packet data.

Parameters:

srcport (AppType | int) – Source port.
dstport (AppType | int) – Destination port.
checksum (bytes | None) – Checksum; if None and CHECKSUM_COMPUTE is on, computed over pseudo (RFC 768), or left to an IP layer this datagram is the payload of; zero, i.e. none, otherwise.
total_length (int | None) – Length of the datagram, header included; computed from the header and the payload when omitted. A jumbogram’s is given as zero (RFC 2675 Section 4).
payload (bytes | Schema | ProtocolBase) – Payload data.
trailer (bytes) – Octets after the datagram, outside the Length field; written as is and not counted in a computed total_length.
pseudo (IP_Pseudo | None) – Pseudo-header of the enclosing IP layer; its length is replaced by total_length, as the Length field gives it.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

UDP

Returns:

Constructed packet data.

Raises:

ProtocolError – If srcport or dstport is a bool (#2287), total_length, given or computed, does not fit 16 bits, or checksum is not two octets.

Changed in version 1.5.0: An out-of-range srcport or dstport raises ValueError rather than being accepted (#758). total_length sits before payload (#1155), so a caller passing payload positionally sets total_length instead.

classmethod __index__()[source]¶

Numeral registry index of the protocol.

Return type:: TransType
Returns:: Numeral registry index of the protocol in IANA.

classmethod _make_data(data)[source]¶

Create key-value pairs from data for protocol construction.

Parameters:: data (UDP) – protocol data
Return type:: dict[str, Any]
Returns:: Key-value pairs for protocol construction.

_verify_pseudo_checksum(pseudo)[source]¶

Verify the checksum over the pseudo-header of the enclosing IP layer.

That layer calls this once parsed, see verify_upper(). A zero checksum over IPv4, which means none (RFC 768), and the pseudo-header’s sum alone, which checksum offload leaves on the sending host, are NOT_COMPUTED. A zero one over IPv6 is wrong, as one is mandatory there (RFC 8200 Section 8.1).

Parameters:: pseudo (IP_Pseudo | None) – Pseudo-header, or None if the IP layer gives none.

Header Schemas¶

Removed in version 1.6.0: pcapkit.protocols.schema.transport.udp, with no alias: the module moved here (#2534).

class pcapkit.protocols.transport.udp.schema.UDP(srcport=NO_VALUE, dstport=NO_VALUE, len=NO_VALUE, checksum=NO_VALUE, payload=NO_VALUE, trailer=NO_VALUE, *, __packet__=None, **kwargs)[source]¶

Bases: Schema

Header schema for UDP packet.

srcport: AppType = <PortEnumField srcport>¶: Source port.

dstport: AppType = <PortEnumField dstport>¶: Destination port.

len: int = <UInt16Field len>¶: Length of UDP packet.

checksum: bytes = <BytesField checksum>¶: Checksum of UDP packet.

payload: bytes = <PayloadField payload>¶: Payload. A Length below the header’s own 8 octets leaves the length negative, which takes the rest of the datagram.

trailer: bytes = <PayloadField trailer>¶: Octets captured past the Length field, see IPv4.trailer.

Data Models¶

Removed in version 1.6.0: pcapkit.protocols.data.transport.udp, with no alias: the module moved here (#2534).

class pcapkit.protocols.transport.udp.data.UDP(srcport, dstport, len, checksum)[source]¶

Bases: Protocol

Data model for UDP protocol.

srcport: AppType¶: Source port.

dstport: AppType¶: Destination port.

len: int¶: Length, header included.

checksum: bytes¶: Checksum.

trailer: bytes¶: Octets captured past the Length field, present only when there are any.

checksum_status: ChecksumStatus¶: Outcome of verifying checksum, present only when the enclosing IP layer verified it under CHECKSUM_VERIFY.

Footnotes