Internet Layer Base Protocol¶
pcapkit.protocols.internet.internet contains Internet,
which is a base class for internet layer protocols, e.g. AH,
IPsec, IPv4,
IPv6 and IPX.
- class pcapkit.protocols.internet.internet.Internet[_PT: Data, _ST: Schema](file=None, length=None, **kwargs)[source]¶
Bases:
ProtocolBase[_PT,_ST],Generic[_PT,_ST]Abstract base class for internet layer protocol family.
This class parses the following protocols, which are registered in the
self.__proto__attribute:Changed in version 1.5.0: A layer parsed as an IPv6 extension header keeps only its own octets in
data, so thatfrom_data(info).datarebuilds it exactly (#1446).- __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 bareintis a valid key too. Declared by the class owning the registry and read byregister_protocol_code(), so acode=key is checked asregister_transtype()checks its own (#2268).IPX, which keeps a registry of its own, declares its own pairing (#2511).
- _exthdr_depth = 0¶
How many IPv6 extension headers in a row the next layer follows: this layer’s place in such a chain, or how many headers
IPv6walked, else0, seeEXTENSION_HEADER_LIMITand_next_exthdr_depth().- Type:
- classmethod register(code, protocol)[source]¶
Register a new protocol class.
Notes
The fully qualified class name should be
{protocol.module}.{protocol.name}.- Parameters:
protocol (
ModuleDescriptor[ProtocolBase] |Type[ProtocolBase]) – module descriptor or aProtocolBasesubclass
- Raises:
pcapkit.utilities.exceptions.RegistryError – If
protocolis not a class, or not aProtocolBasesubclass.- Warns:
pcapkit.utilities.warnings.RegistryWarning– If this protocol number is already registered, naming the displaced entry and its replacement so a caller can tell what was lost. Fires only when the incumbent differs from the replacement; seeProtocol.registerfor the guard this shares withregister_protocol, and for the shipped descriptor a restore puts back (#1504).
Changed in version 1.3.0: Takes the class, or a
ModuleDescriptornaming it, asprotocol, in place of themoduleandclass_name strings.
- classmethod from_data(data, **kwargs)[source]¶
Create protocol instance from data.
An IPv6 extension header parsed alone always holds a next layer in its data model, so one whose data model holds none is rebuilt with
extension, unlesskwargsgive it.- Parameters:
**kwargs (
Any) – Construction keywords, as forProtocol.from_data.
- Return type:
- Returns:
Protocol instance, cut back to what was captured when the header it was parsed from was cut short (#1458).
Changed in version 1.6.0: Such a header is rebuilt with
extension, rather than with a next layer its parse did not hold (#2768).
- _next_exthdr_depth(proto, extension=False)[source]¶
Place the next layer in its chain of IPv6 extension headers.
- Parameters:
extension (
bool) – if the next layer is parsed as an extension header byIPv6’s walk, which counts the chain itself, seeIPv6._decode_next_layer
- Return type:
- Returns:
One more than
_exthdr_depthifprotonames an IPv6 extension header, or0if it names none, so that another layer between two headers starts a new chain. PastEXTENSION_HEADER_LIMIT, the next layer is left raw.
- classmethod _rebuilt_exthdr_depth()[source]¶
Place a layer
from_data()rebuilds in its chain of IPv6 extension headers.- Return type:
- Returns:
Where
_make_payload()of the layer it is the payload of puts it, if it is an IPv6 extension header, or0if it is not, as_next_exthdr_depth()places a layer being parsed. A layer rebuilt on its own is at0, as one parsed from its own octets is.
- classmethod _make_payload(data)[source]¶
Create payload from
datafor protocol construction.As
Protocol._make_payload, but the payload is built at its place in its chain of IPv6 extension headers, one past this layer’s, since it parses its own octets again. So rebuilding a frame stops atEXTENSION_HEADER_LIMITwhere parsing it did, rather than that many headers past each header of the chain, and warns of the limit once, as_next_layer_class()describes (#1619).- Parameters:
data (
Data) – protocol data- Return type:
- Returns:
Payload for protocol construction.
- _next_layer_class(proto, file_, length, extension=False)[source]¶
Pick the class the next layer is parsed with.
- Parameters:
- Return type:
- Returns:
The class
_empty_next_layer()gives if there is nothing to parse;Rawif the parse stops at this layer, or the next layer is an IPv6 extension header pastEXTENSION_HEADER_LIMITin a row; otherwise the class registered forproto. Paired with it, the keywords that only that next layer is constructed with: the warning given, aserror, or the next layer’s place in its chain, as_exthdr_depth.- Warns:
ProtocolWarning– If the next layer is pastEXTENSION_HEADER_LIMIT(#1604), unless this layer is inside a payload being rebuilt (#1619).
- _decode_next_layer(dict_, proto=None, length=None, *, packet=None, version=4, ipv6_exthdr=None, payload=None, declared=True)[source]¶
Decode next layer extractor.
- Parameters:
dict_ (
_PT) – info bufferpacket (
dict[str,Any] |None) – packet info (passed fromself.unpack)version (
Literal[4,6]) – IP versionipv6_exthdr (
ProtoChain|None) – protocol chain of IPv6 extension headerspayload (
bytes|None) – payload from packet. If not provided, will extract fromself.__header__.get_payloaddeclared (
bool) – whether this layer declares the length of its payload
- Return type:
_PT- Returns:
Current protocol with next layer extracted.
Notes
dict_gains the keys__next_type__(next layer protocol type) and__next_name__(next layer protocol name), whichInfo.to_dictcarries and the dumpers leave out.The next layer is parsed with
frame_lengthcleared, since this layer, not the frame, bounds its payload (#2653). Withdeclaredfalse it is left as it is, for a payload that runs to the end of the frame, as behind an IPv4 Total Length of 0, or to the end of the parent’s (#2689).
- _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 indexpacket (
dict[str,Any] |None) – packet info (passed fromself.unpack)version (
Literal[4,6]) – IP protocol versionextension (
bool) – if is extension headerpayload (
bytes|None) – payload from packet. If not provided, will extract fromself.__header__.get_payload
- Return type:
- Returns:
Instance of next layer.
Notes
An IPv6 extension header past
EXTENSION_HEADER_LIMITin a row is not dissected: it and the rest of the packet are kept asRaw, with oneProtocolWarning(#1604). Each header dissects the next one from here, so the chain’s depth is handed to the next layer, see_next_layer_class().
- pcapkit.protocols.internet.internet._exthdr_rebuilt¶
Where the payload
Internet._make_payload()rebuilds sits in a chain of IPv6 extension headers, should it be one: one past the layer it is the payload of, asInternet._next_exthdr_depth()places it while parsing, seeEXTENSION_HEADER_LIMIT.- Type:
Extension Header Chains¶
A chain of IPv6 extension headers, behind IPv6 or another layer such as IPv4,
is dissected to at most EXTENSION_HEADER_LIMIT
headers in a row. What follows is kept as
Raw, with one
ProtocolWarning (#1604). The other
engines and toolkits:
Engine or toolkit |
Behind a chain |
|---|---|
|
Its own parser walks the chain without that limit, so it may still find the upper layer (#1609). |
|
Reads the chain as |
|
Behind IPv6, Scapy dissects each extension header itself, so it may too.
Behind IPv4, its toolkit steps over at most
|
|
Walks no chain, so it finds no upper layer behind one. |