IPv6 - Internet Protocol version 6¶

pcapkit.protocols.internet.ipv6 contains IPv6 only, which implements extractor for Internet Protocol version 6 (IPv6) [*], whose structure is described as below:

Octets	Bits	Name	Description
0	0	`ipv6.version`	Version (`6`)
0	4	`ipv6.class`	Traffic Class
1	12	`ipv6.label`	Flow Label
4	32	`ipv6.payload`	Payload Length (header excludes)
6	48	`ipv6.next`	Next Header
7	56	`ipv6.limit`	Hop Limit
8	64	`ipv6.src`	Source Address
24	192	`ipv6.dst`	Destination Address

class pcapkit.protocols.internet.ipv6.IPv6(file=None, length=None, **kwargs)[source]¶

Bases: IP[IPv6, IPv6]

This class implements Internet Protocol version 6.

Changed in version 1.5.0:

A Shim6 header, which has no dedicated parser, and a header in __generic_ext_codes__ whose dedicated parser raises are parsed by IPv6_Ext, so the rest of the chain is still walked (#891).
A rebuild from from_data() keeps the Payload Length a truncated capture declares (#1155), and the octets past it as trailer (#1209).
Next Header codes 253 and 254 are parsed and rebuilt once (#1231), and a cut extension header chain rebuilds byte for byte (#1471, #1473).

property name: Literal['Internet Protocol version 6']¶: Name of corresponding protocol.

property length: Literal[40]¶: Header length of corresponding protocol.

property protocol: TransType¶: Name of next layer protocol.

property src: IPv6Address¶: Source IP address.

property dst: IPv6Address¶: Destination IP address.

property extension_headers: OrderedMultiDict[ExtensionHeader, ProtocolBase]¶: IPv6 extension header records.

classmethod id()[source]¶

Index ID of the protocol.

Return type:: tuple[Literal['IPv6']]
Returns:: Index ID of the protocol.

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

Read Internet Protocol version 6 (IPv6).

Structure of IPv6 header [RFC 8200]:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Version| Traffic Class |           Flow Label                  |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|         Payload Length        |  Next Header  |   Hop Limit   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+                                                               +
|                                                               |
+                         Source Address                        +
|                                                               |
+                                                               +
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                                                               |
+                                                               +
|                                                               |
+                      Destination Address                      +
|                                                               |
+                                                               +
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Parameters:

length (int | None) – Length of packet data.
__packet__ (dict[str, Any] | None) – Optional packet data.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

IPv6

Returns:

Parsed packet data.

Raises:

ProtocolError – If the version is not 6, or if the packet is one of the errors RFC 2675 Section 3 has a receiver detect (see jumbogram_error()).

make(traffic_class=0, flow_label=0, next=<TransType.UDP: 17>, next_default=None, next_namespace=None, next_reversed=False, hop_limit=64, src='::1', dst='::', payload_length=None, payload=b'', trailer=b'', **kwargs)[source]¶

Make (construct) packet data.

Parameters:

traffic_class (int) – Traffic class.
flow_label (int) – Flow label.
next (TransType | IntEnum | IntEnum | str | int) – Next header.
next_default (int | None) – Default value of next header.
next_namespace (dict[str, int] | dict[int, str] | Type[IntEnum] | Type[IntEnum] | None) – Namespace of next header.
next_reversed (bool) – Whether to reverse the namespace of next header.
hop_limit (int) – Hop limit.
src (IPv6Address | str | bytes | int) – Source IP address.
dst (IPv6Address | str | bytes | int) – Destination IP address.
payload_length (int | None) – Length of the payload, extension headers included; computed from the payload when omitted, and zero (a jumbogram) if that exceeds 65,535 octets or the payload starts with a Hop-by-Hop Options header carrying a Jumbo Payload option.
payload (bytes | ProtocolBase | Schema) – Payload data.
trailer (bytes) – Octets after the packet, outside the Payload Length, such as link-layer padding; written as is.
**kwargs (Any) – Arbitrary keyword arguments.

Return type:

IPv6

Returns:

Constructed packet data.

classmethod _make_data(data)[source]¶

Create key-value pairs from data for protocol construction.

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

_decode_next_layer(ipv6, proto=None, length=None, *, packet=None)[source]¶

Decode next layer extractor.

Parameters:

ipv6 (IPv6) – info buffer
proto (int | None) – next layer protocol index
length (int | None) – valid (not padding) length
packet (dict[str, Any] | None) – packet info (passed from self.unpack)

Return type:

IPv6

Returns:

Current protocol with next layer extracted.

Raises:

ProtocolError – If the walk reaches a Fragment header in a packet carrying a Jumbo Payload option, an error by RFC 2675 Section 3 (#1687).

_import_next_layer(proto, length=None, *, packet=None, version=4, extension=False, payload=None)[source]¶

Import next layer extractor.

Parameters:

proto (int) – next layer protocol index
length (int | None) – valid (non-padding) length
packet (dict[str, Any] | None) – packet info (passed from self.unpack)
version (Literal[4, 6]) – IP protocol version
extension (bool) – if is extension header
payload (bytes | None) – payload from packet. If not provided, will extract from self.__header__.get_payload

Return type:

ProtocolBase

Returns:

Instance of next layer.

Notes

If the dedicated parser for a code in __generic_ext_codes__ raises, this substitutes IPv6_Ext for it rather than letting the exception reach the beholder() decorating this method, which would substitute plain Raw – and Raw has no next field, so it could not continue _decode_next_layer()’s walk. Every other exception – including one raised by IPv6_Ext itself, or by ESP’s own dedicated parser – still reaches beholder unchanged, giving a plain Raw for that one layer. 253 and 254 have no dedicated parser, so they reach plain Raw with no exception involved; _decode_next_layer() stops its walk structurally on any layer whose info carries no next attribute, Raw included. ESP’s info always carries a next (None, since RFC 4303 encrypts the real value), so neither this substitution nor that structural check engages for it, and the walk ends after it – see __generic_ext_codes__’s docstring for the full distinction.

The upper layer past a walk cut at EXTENSION_HEADER_LIMIT is the next extension header, and is kept raw with one ProtocolWarning, as in Internet._import_next_layer (#1604).

classmethod __index__()[source]¶

Numeral registry index of the protocol.

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

__generic_ext_codes__¶

Extension header codes with a dedicated parser class in this package whose layout follows RFC 6564 Section 4’s generic next + Hdr Ext Len format (see the module docstring of pcapkit.protocols.internet.ipv6_ext for the exception table). When that dedicated parser raises, _import_next_layer() substitutes IPv6_Ext instead of letting the generic beholder() fall back to plain Raw, which has no next field and so cannot continue the walk in _decode_next_layer().

Three groups are deliberately absent:

Shim6 has no dedicated parser class in this package, so there is no “own parser” for it to raise from. It reaches IPv6_Ext by direct registration (see the bottom of pcapkit.protocols.internet.ipv6_ext), which already produces exactly this class.
ESP does have a dedicated, registered parser (ESP). It is excluded because RFC 4303 places the real Next Header byte inside the encrypted trailer, so its own info always carries a next attribute, just one that is None whenever the payload could not be decrypted – which, with no key material available to a generic parse, is always. The _decode_next_layer() walk still ends there, one iteration later, because None fails ExtensionHeader’s constructor at the top of the loop – the ordinary end-of-chain path, unrelated to the structural check this set exists for.
253 and 254 have no dedicated parser at all, so they resolve to plain Raw, whose info has no next attribute; the structural check in _decode_next_layer() catches these. A next-header byte that is not in the extension-header registry at all (e.g. 147) fails the same constructor at the top of the loop, like any unrecognised upper-layer protocol code.

_decode_next_layer()’s walk stops cleanly at whichever of these (or any other IANA code this package has not implemented) it meets, and keeps this layer’s own header intact.

Protocol Constants¶

pcapkit.protocols.internet.ipv6.IPV6_HEADER_LEN = 40¶: Length of the fixed IPv6 header, i.e. the offset of the first extension header, RFC 8200 Section 3. The one home of this value (#1739); it is fixed by the RFC, so it is never configurable.

Added in version 1.5.0.

pcapkit.protocols.internet.ipv6.IPV6_NEXT_HEADER_OFFSET = 6¶: Offset of the Next Header field within the fixed IPv6 header, RFC 8200 Section 3. The one home of this value (#1739).

Added in version 1.5.0.

Header Schemas¶

pcapkit.protocols.schema.internet.ipv6.IP_MAX_LENGTH = 65535¶

IPv4’s Total Length, the header included (RFC 791 Section 3.1), and IPv6’s Payload Length, the fixed header excluded (RFC 8200 Section 3) – so a longer IPv6 payload is a jumbogram, whose Jumbo Payload Length must exceed it (RFC 2675 Section 2). The one home of this value (#1739), here so that the schema’s jumbogram check and the protocol modules read the same one; it is fixed by the RFCs, so it is never configurable.

Added in version 1.5.0.

Type:: The most octets a 16-bit IP length field declares

class pcapkit.protocols.schema.internet.ipv6.IPv6(*args: _VT, **kwargs: _VT)[source]¶

Bases: Schema

Header schema for IPv6 packet.

hextet: IPv6Hextet = <BitField hextet>¶

Version, traffic class and flow label.

The BitField namespace maps each subfield to a (start_bit, length_in_bits) pair, not to (start_bit, end_bit). Per RFC 8200 Section 3 the first 32 bits of the IPv6 header are Version (bits 0-3), Traffic Class (bits 4-11) and Flow Label (bits 12-31), so the flow label starts at bit 12 – reading it as (8, 20) would overlap the low nibble of the traffic class and drop the low nibble of the label.

length: int = <UInt16Field length>¶: Payload length.

next: TransType = <EnumField next>¶: Next header.

limit: int = <UInt8Field limit>¶: Hop limit.

src: IPv6Address = <IPv6AddressField src>¶: Source address.

dst: IPv6Address = <IPv6AddressField dst>¶: Destination address.

payload: bytes = <PayloadField payload>¶: Payload.

trailer: bytes = <PayloadField trailer>¶: Octets captured past the Payload Length (or a jumbogram’s Jumbo Payload Length, see post_process()), such as Ethernet minimum-frame padding, c.f. IPv4.trailer.

post_process(packet)[source]¶

Revise schema data after unpacking process.

A jumbogram [RFC 2675] declares a Payload Length of zero and carries its real length in a Jumbo Payload option instead, so the payload field reads nothing and every octet lands in trailer. When jumbo_payload_length() finds that option, the two are split again at the Jumbo Payload Length, and only the octets beyond it stay in trailer. The octets themselves are untouched, so the packed header is unchanged.

Parameters:: packet (dict[str, Any]) – Unpacked data.
Return type:: Schema
Returns:: Revised schema.

Type Stubs¶

class pcapkit.protocols.schema.internet.ipv6.IPv6Hextet¶

Bases: TypedDict

Version, traffic class and flow label.

version: int¶: Version.

class: int¶: Traffic class.

label: int¶: Flow label.

Auxiliary Functions¶

pcapkit.protocols.schema.internet.ipv6.jumbo_payload_length(next, data)[source]¶

Find the Jumbo Payload Length of an IPv6 packet [RFC 2675].

The Jumbo Payload option is only honoured in a Hop-by-Hop Options header that immediately follows the IPv6 header, as RFC 2675 Section 2 and RFC 8200 Section 4.1 place it there; one anywhere else is left to the extension header that carries it.

Parameters:

next (int) – Next Header of the IPv6 header.
data (bytes) – Octets following the IPv6 header.

Return type:

int | None

Returns:

The Jumbo Payload Length, or None if data does not start with a Hop-by-Hop Options header carrying a well-formed (four-octet) Jumbo Payload option.

pcapkit.protocols.schema.internet.ipv6.jumbogram_error(length, next, data, fragment=None)[source]¶

Name the error RFC 2675 Section 3 has a receiver detect in an IPv6 packet, if any.

The four errors that section lists for a node that understands the Jumbo Payload option, each a packet the default engine rejects (#1687):

a Payload Length of zero, a Next Header of Hop-by-Hop Options, and no Jumbo Payload option;
a non-zero Payload Length and a Jumbo Payload option;
a Jumbo Payload option whose Jumbo Payload Length is below 65,536;
a Jumbo Payload option and a Fragment header.

The option counts only where jumbo_payload_length() finds it.

Parameters:

length (int) – Payload Length of the IPv6 header.
next (int) – Next Header of the IPv6 header.
data (bytes) – Octets following the IPv6 header, as captured.
fragment (Callable[[], bool] | None) – Tells whether the extension header chain, as the default engine walks it, has a Fragment header; called only for a packet carrying the option, so a caller walks the chain only for those.

Return type:

str | None

Returns:

The error, or None if the packet makes none of them.

Data Models¶

class pcapkit.protocols.data.internet.ipv6.IPv6(*args: Any, **kwargs: Any)[source]¶

Bases: Protocol

Data model for Internet Protocol version 6.

Important

Due to the reserved keyword conflict, please use from_dict() to create an instance of this data model.

class: int¶: Traffic class.

Note

This field is conflict with class keyword. To access this field, directly use getattr() instead.

version: Literal[6]¶: Version.

label: int¶: Flow label.

payload: int¶: Payload length.

next: TransType¶: Next header.

limit: int¶: Hop limit.

src: IPv6Address¶: Source address.

dst: IPv6Address¶: Destination address.

fragment: Packet¶: Fragmented packet header & payload (from IPv6-Frag header).

protocol: TransType¶: Highest header protocol type (extension header excluded).

hdr_len: int¶: Header length (including extension headers).

raw_len: int¶: Raw payload length (excluding extension headers).

trailer: bytes¶: Octets captured past the Payload Length – or, for a jumbogram, past the Jumbo Payload Length – present only when there are any.

Footnotes