IPv6 - Internet Protocol Version 6

Removed in version 1.6.0: pcapkit.protocols.internet.ipv6.IPV6_HEADER_LEN and pcapkit.protocols.internet.ipv6.IPV6_NEXT_HEADER_OFFSET, with no alias: they are in this module, and pcapkit.protocols.internet.ipv6 exports the protocol class alone (#2534).

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

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 excluded)

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.protocol.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 an extension header other than ESP 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).

Changed in version 1.6.0:

  • An extension header whose dedicated parser raises is the upper layer, parsed once as Raw, and the chain walk stops there, as RFC 8200 Section 4 has a node discard such a packet (#2477).

  • next of make() takes a member or an int code, resolved with the enumeration’s get; a name, a bool, or a code that does not fit in one octet raises ProtocolError, rather than resolving against an enumeration inferred from the caller’s frame or writing a different value (#2594).

Removed in version 1.6.0:

  • __generic_ext_codes__, the extension headers whose dedicated parser raising fell back to IPv6_Ext (#2477).

  • The next_default, next_namespace and next_reversed arguments of make(); resolve a name with resolve_index() first (#2594).

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.

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, 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 | int) – 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.

Raises:

ProtocolError – If next is a name, a bool, or a member or code that does not fit in one octet.

Changed in version 1.5.0: Takes payload_length ahead of payload (#1155), which shifts a positional payload.

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

Unpack (parse) packet data.

The Version field is checked before the header schema is parsed, so octets of another version are refused as such, rather than by whichever field of this header they break first (#2574).

Parameters:

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

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

Return type:

IPv6

Returns:

Parsed packet data.

Raises:

ProtocolError – If the Version field is not 6.

classmethod id()[source]

Index ID of the protocol.

Return type:

tuple[Literal['IPv6']]

Returns:

Index ID of the protocol.

classmethod __index__()[source]

Numeral registry index of the protocol.

Return type:

TransType

Returns:

Numeral registry index of the protocol in IANA.

__post_init__(file=None, length=None, **kwargs)[source]

Post initialisation hook.

Once parsed, the checksum of the upper layer is verified over this layer’s pseudo-header if CHECKSUM_VERIFY is on, see verify_upper().

Parameters:

  • file (IO[bytes] | bytes | None) – Source packet stream.

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

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

Return type:

None

See also

For construction arguments, please refer to make().

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:
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).

_read_ip_hextet()[source]

Read the first four octets of IPv6.

Returns:

version number, traffic class and flow label.

Return type:

tuple[int, int, int]

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

Import next layer extractor.

Parameters:
Return type:

ProtocolBase

Returns:

Instance of next layer.

Notes

A header whose dedicated parser raises reaches the beholder() decorating this method, which substitutes plain Raw. That carries no next, so _decode_next_layer()’s walk stops there, as RFC 8200 Section 4 has a node discard such a packet (#2477). 253 and 254 have no dedicated parser and reach plain Raw with no exception involved, which stops the walk the same way. A Raw the walk stopped on is then returned as the upper layer, not parsed again. ESP’s info always carries a next, None unless its payload was decrypted, since RFC 4303 encrypts the real value, so the walk ends after it.

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).

Protocol Constants

pcapkit.protocols.internet.ipv6.protocol.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.protocol.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

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

Removed in version 1.6.0: pcapkit.protocols.schema.internet.ipv6.jumbo_payload_length, now pcapkit.corekit.schema.jumbogram.jumbo_payload_length() (#2674).

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

The most octets a 16-bit IP length field declares, for IPv4’s Total Length the header included (RFC 791 Section 3.1) and for IPv6’s Payload Length the fixed header excluded (RFC 8200 Section 3); 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.

class pcapkit.protocols.internet.ipv6.schema.IPv6(hextet=NO_VALUE, length=NO_VALUE, next=NO_VALUE, limit=NO_VALUE, src=NO_VALUE, dst=NO_VALUE, payload=NO_VALUE, trailer=NO_VALUE, *, __packet__=None, **kwargs)[source]

Bases: Schema

Header schema for IPv6 packet.

Changed in version 1.5.0: New field trailer, which keeps the octets captured past the Payload Length rather than dropping them (#1209).

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, see 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.internet.ipv6.schema.IPv6Hextet

Bases: TypedDict

Version, traffic class and flow label.

version: int

Version.

class: int

Traffic class.

label: int

Flow label.

Auxiliary Functions

pcapkit.protocols.internet.ipv6.schema.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

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

class pcapkit.protocols.internet.ipv6.data.IPv6(version, label, payload, next, limit, src, dst)[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’s name conflicts with the class keyword, so access it with 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