Skip to content

Commit e331c1a

Browse files
committed
docs(changelog): fold the makers' refusal of an empty raw item into 1.6.0 (#2449)
- Fixed: an empty raw option, parameter, cause, sub-option, attribute, CGA extension or PCAP-NG option or record shorter than its code raises ProtocolError (#2728), into the TCP and HIP makers' Fixed entry beside TCP's own; the IPv4, HOPOPT, IPv6-Opts, SCTP, MH, HIP and PCAP-NG outcomes measured against v1.5.1. - Folded into unreleased entries: DCCP's empty raw option (#2728). - No entry for the docstring-only 596dcfa and 6b63ee9, or the test-only 219fbbc. - CHANGELOG.md regenerated; util/changelog_md.py --check passes.
1 parent d85ffb0 commit e331c1a

2 files changed

Lines changed: 16 additions & 4 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Wave 2 of the roadmap, per the contributing docs' enhancement-proposal page: the
2020

2121
- **Added** -- construction through a versioned family's base: `IP` and `L2TP`, which raised `TypeError` in 1.5.x, and the `ICMP`, `IGMP` and `LinuxSLL` bases above give a member, never an instance of the base, on parsing octets, building from fields and `from_data` ([#2574](https://github.com/JarryShaw/PyPCAPKit/issues/2574), [#2639](https://github.com/JarryShaw/PyPCAPKit/pull/2639)). The `version` keyword names the member. Without it, IP's, IGMP's and L2TP's octets give the member they describe, and `from_data` the one its data names, IGMP's data models carrying a `version` for it. Building from fields without it raises `ProtocolError`, whose message asks for `version`, and so do ICMP and Linux cooked-capture octets, which carry no version; their `from_data` on a `dict` raises it too, as does a version a family has no member for, such as L2TP's `3`. A member built directly takes `version` as well, which must be its own. HTTP's base follows the same rules, a breaking change given below ([#2628](https://github.com/JarryShaw/PyPCAPKit/issues/2628), [#2651](https://github.com/JarryShaw/PyPCAPKit/pull/2651)). IPv4 and IPv6 check the Version field before the rest of the header, so octets of the other version raise `[IPv4] invalid version: 6` say, where IPv4's error named whichever field they broke first.
2222

23-
- **Added** -- `DCCP` ([RFC 4340](https://datatracker.ietf.org/doc/html/rfc4340)) for IP protocol 33, which was kept as `Raw` ([#2489](https://github.com/JarryShaw/PyPCAPKit/issues/2489), [#2593](https://github.com/JarryShaw/PyPCAPKit/pull/2593)). It reads and builds the generic header with short and long sequence numbers, the fields of every packet type, DCCP-Listen ([RFC 5596](https://datatracker.ietf.org/doc/html/rfc5596)) and the options; the Data Checksum option's CRC-32c is recorded rather than checked. Its checksum is verified and computed as TCP's is, below, over the enclosing IP layer's pseudo-header and the part of the packet its Checksum Coverage gives ([RFC 4340 Section 9.2](https://datatracker.ietf.org/doc/html/rfc4340#section-9.2)): a coverage running past the packet is `INVALID` and warns, and a `make()` that computes the checksum writes a coverage reaching the end of the packet as 0, as Linux did. `register_dccp()` registers a port's dissector, and `register_dccp_option()` an option parser. The registries are `pcapkit.const.dccp`, crawled from IANA. Its `make()` refuses a value a field cannot hold with `ProtocolError` naming the field ([#2614](https://github.com/JarryShaw/PyPCAPKit/issues/2614), [#2670](https://github.com/JarryShaw/PyPCAPKit/pull/2670)).
23+
- **Added** -- `DCCP` ([RFC 4340](https://datatracker.ietf.org/doc/html/rfc4340)) for IP protocol 33, which was kept as `Raw` ([#2489](https://github.com/JarryShaw/PyPCAPKit/issues/2489), [#2593](https://github.com/JarryShaw/PyPCAPKit/pull/2593)). It reads and builds the generic header with short and long sequence numbers, the fields of every packet type, DCCP-Listen ([RFC 5596](https://datatracker.ietf.org/doc/html/rfc5596)) and the options; the Data Checksum option's CRC-32c is recorded rather than checked. Its checksum is verified and computed as TCP's is, below, over the enclosing IP layer's pseudo-header and the part of the packet its Checksum Coverage gives ([RFC 4340 Section 9.2](https://datatracker.ietf.org/doc/html/rfc4340#section-9.2)): a coverage running past the packet is `INVALID` and warns, and a `make()` that computes the checksum writes a coverage reaching the end of the packet as 0, as Linux did. `register_dccp()` registers a port's dissector, and `register_dccp_option()` an option parser. The registries are `pcapkit.const.dccp`, crawled from IANA. Its `make()` refuses a value a field cannot hold with `ProtocolError` naming the field ([#2614](https://github.com/JarryShaw/PyPCAPKit/issues/2614), [#2670](https://github.com/JarryShaw/PyPCAPKit/pull/2670)), and an option given as empty raw octets ([#2723](https://github.com/JarryShaw/PyPCAPKit/issues/2723), [#2728](https://github.com/JarryShaw/PyPCAPKit/pull/2728)).
2424

2525
- **Added** -- `TLS` (SSLv3 and TLS 1.0 to 1.3) at TCP 443 and `DTLS` (DTLS 1.0, 1.2 and 1.3) at UDP 5684, on an abstract `SSL` base ([#2437](https://github.com/JarryShaw/PyPCAPKit/issues/2437), [#2441](https://github.com/JarryShaw/PyPCAPKit/pull/2441)). Each reads every version of its record layer and reports it through `alias`, as `ARP` does by operation, telling 1.3 apart by its `supported_versions` extension; `id()` stays `('TLS',)` or `('DTLS',)`. A cleartext handshake record is decoded -- ClientHello and ServerHello down to their cipher suites, compression methods and extensions, EncryptedExtensions down to its extensions, any other message at type and length -- as are an alert and ChangeCipherSpec, while encrypted records stay opaque octets. An extension's body is read and built for `server_name`, `supported_groups`, `signature_algorithms`, ALPN, `supported_versions` and `key_share`, a HelloRetryRequest's included, and kept as octets for any other type or for a body its parser rejects, which logs nothing; `register_tls_extension()` registers a parser and constructor for a further type ([#2514](https://github.com/JarryShaw/PyPCAPKit/issues/2514), [#2595](https://github.com/JarryShaw/PyPCAPKit/pull/2595)). `make()` refuses a value too wide for its field, in the record header or in the content it builds, with `StructError` ([#2614](https://github.com/JarryShaw/PyPCAPKit/issues/2614), [#2638](https://github.com/JarryShaw/PyPCAPKit/pull/2638)), and a name, or a code too wide, for an enumeration field with `ProtocolError`, as the other makers do, below ([#2594](https://github.com/JarryShaw/PyPCAPKit/issues/2594), [#2692](https://github.com/JarryShaw/PyPCAPKit/pull/2692)). Each whole TLS record in a TCP segment is a layer of its own, the previous record's payload, so each alias names its own version -- `TCP:TLS 1.3:TLS 1.2` -- and one that fails to decode is `Raw` with the rest of the segment ([#2517](https://github.com/JarryShaw/PyPCAPKit/issues/2517), [#2537](https://github.com/JarryShaw/PyPCAPKit/pull/2537)). `SSLv3`, in `pcapkit.protocols.application.sslv3` ([#2529](https://github.com/JarryShaw/PyPCAPKit/issues/2529), [#2602](https://github.com/JarryShaw/PyPCAPKit/pull/2602)), exists for explicit construction only. A record split across TCP segments is not reassembled and stays `Raw`. DTLS also reads and builds the DTLS 1.3 unified-header records of [RFC 9147 Section 4.1](https://datatracker.ietf.org/doc/html/rfc9147#section-4.1) ([#2467](https://github.com/JarryShaw/PyPCAPKit/issues/2467), [#2494](https://github.com/JarryShaw/PyPCAPKit/pull/2494)) and [RFC 9146](https://datatracker.ietf.org/doc/html/rfc9146) `tls12_cid` records. A `DTLSContext`, given to `extract()` as its `context`, resolves the connection ID of a `tls12_cid` record, or of a unified-header record with its `C` bit set ([#2625](https://github.com/JarryShaw/PyPCAPKit/issues/2625), [#2643](https://github.com/JarryShaw/PyPCAPKit/pull/2643)), from those the capture's hellos negotiate in their `connection_id` extension, which TLS and DTLS both decode, or from the `cid_length` the caller gives it, and one it cannot resolve stays Raw. An ID a DTLS 1.3 `NewConnectionId` issues is encrypted, so only the caller can give it. A unified-header record's `info` carries its ID as `cid`, `None` when the `C` bit is clear, as `length` is when the `L` bit is, so that the one header keeps one data model, as settled on [#2625](https://github.com/JarryShaw/PyPCAPKit/issues/2625); its `make()` takes a `cid` and sets the `C` bit. `pcapkit.protocols.data` and `pcapkit.protocols.schema` export a `tls12_cid` record's classes as `DTLS_CIDCiphertext` and the extension's data model as `TLS_ConnectionId` ([#2515](https://github.com/JarryShaw/PyPCAPKit/issues/2515), [#2631](https://github.com/JarryShaw/PyPCAPKit/pull/2631), [#2641](https://github.com/JarryShaw/PyPCAPKit/pull/2641)). Each whole DTLS record in a UDP datagram is likewise a layer of its own -- a DTLS 1.2 record then a DTLS 1.3 unified-header record read `DTLS 1.2:DTLS 1.3` -- a unified-header record with no length running to the end of the datagram, and one that fails to decode is `Raw` with the rest of the datagram ([#2535](https://github.com/JarryShaw/PyPCAPKit/issues/2535), [#2603](https://github.com/JarryShaw/PyPCAPKit/pull/2603)). The content, handshake and extension types are `pcapkit.const.tls`, crawled from IANA ([#2495](https://github.com/JarryShaw/PyPCAPKit/issues/2495), [#2514](https://github.com/JarryShaw/PyPCAPKit/issues/2514), [#2503](https://github.com/JarryShaw/PyPCAPKit/pull/2503), [#2595](https://github.com/JarryShaw/PyPCAPKit/pull/2595)).
2626

@@ -116,7 +116,7 @@ Wave 2 of the roadmap, per the contributing docs' enhancement-proposal page: the
116116

117117
- **Fixed** -- an `SCTP` packet the capture cut short of the length declared for it, by an IPv4 Total Length, an IPv6 Payload Length or a caller's `length`, rebuilt through `from_data` without the octets after its last whole chunk, which its header schema's `bytes()` counted twice. It rebuilds as captured, as one parsed with no length declared did ([#2673](https://github.com/JarryShaw/PyPCAPKit/issues/2673), [#2679](https://github.com/JarryShaw/PyPCAPKit/pull/2679)). Its header schema cut inside the padding of its last chunk, parameter or cause, or such an item's own schema cut inside its padding, packs back as captured, where 1.5.x packed it at full width, 34 octets in and 36 out; and a header schema cut inside an option area packs back the octets read, where a TCP header schema of data offset 8 cut 25 octets in gave 32 octets from `bytes()` and 23 from `pack()` ([#2680](https://github.com/JarryShaw/PyPCAPKit/issues/2680), [#2685](https://github.com/JarryShaw/PyPCAPKit/issues/2685), [#2682](https://github.com/JarryShaw/PyPCAPKit/pull/2682)).
118118

119-
- **Fixed** -- `TCP`'s maker, given an option as raw octets, raised `EnumValueError` for a kind its registry does not name, such as 255, and `IndexError` for empty octets. The kind resolves as a `(code, arguments)` pair's does, so 255 builds, and empty octets raise `ProtocolError` ([#2708](https://github.com/JarryShaw/PyPCAPKit/issues/2708), [#2724](https://github.com/JarryShaw/PyPCAPKit/pull/2724)). `HIP(next=59)` wrote HIP version 6, taking the IP version for it, and writes 2, `make()`'s default from [RFC 7401 Section 5.1](https://datatracker.ietf.org/doc/html/rfc7401#section-5.1). HIP's `ENCRYPTED` maker refuses an IV given with a cipher that takes none, which 1.5.x counted in the parameter's Length but did not write. A parsed `ENCRYPTED` parameter takes its cipher from the `HIP_CIPHER` before it, where 1.5.x warned `HIP: [ParamNo 641] missing HIP_CIPHER parameter` and read an AES IV as encrypted data.
119+
- **Fixed** -- `TCP`'s maker, given an option as raw octets, raised `EnumValueError` for a kind its registry does not name, such as 255, and `IndexError` for empty octets. The kind resolves as a `(code, arguments)` pair's does, so 255 builds, and empty octets raise `ProtocolError` ([#2708](https://github.com/JarryShaw/PyPCAPKit/issues/2708), [#2724](https://github.com/JarryShaw/PyPCAPKit/pull/2724)). The other makers taking a raw item refuse empty octets the same way, as `IPv4: invalid option: b'' holds no type octet` ([#2723](https://github.com/JarryShaw/PyPCAPKit/issues/2723), [#2728](https://github.com/JarryShaw/PyPCAPKit/pull/2728)). IPv4's, HOPOPT's and IPv6-Opts' options raised `IndexError`. SCTP's parameters and error causes, and MH's options, sub-options, QoS attributes and CGA extensions, raised a bare `AttributeError` alone -- or, for MH's access network identifier and LMA-controlled MAG sub-options, a `ProtocolError` for an option of length 0 -- and were dropped beside a whole item. HIP's parameters were dropped. PCAP-NG's options and Name Resolution records refuse octets shorter than their 2-octet code, where 1.5.x wrote empty or zero octets as an end-of-options or end-of-records marker, and misread one other octet as a code. `HIP(next=59)` wrote HIP version 6, taking the IP version for it, and writes 2, `make()`'s default from [RFC 7401 Section 5.1](https://datatracker.ietf.org/doc/html/rfc7401#section-5.1). HIP's `ENCRYPTED` maker refuses an IV given with a cipher that takes none, which 1.5.x counted in the parameter's Length but did not write. A parsed `ENCRYPTED` parameter takes its cipher from the `HIP_CIPHER` before it, where 1.5.x warned `HIP: [ParamNo 641] missing HIP_CIPHER parameter` and read an AES IV as encrypted data.
120120

121121
- **Fixed** -- a `PCAPNG` Decryption Secrets Block that `make()` built from a parsed ZigBee NWK or APS key shorter than its fixed width was corrupt: it declared that width, 18 or 22 octets, as its Secrets Length and sized the block from it, but wrote only the octets held, so a 5-octet NWK key built a 27-octet block declaring 40, where 28 were captured. It is written as captured, and `pcapkit.protocols.schema.misc.pcapng.zigbee_key_held` returns a schema whose `bytes()` and `len()` are those of the octets held, where they were the fixed width's ([#2688](https://github.com/JarryShaw/PyPCAPKit/issues/2688), [#2697](https://github.com/JarryShaw/PyPCAPKit/pull/2697)). Rebuilt by `from_data` from the block's `dict`, a TLS or WireGuard key log was written from its entries under a `# generated by PyPCAPKit` line, dropping its comments and the lines its entries do not hold, and a ZigBee key cut short of its fixed width was written at that width, zero-filled. The TLS, WireGuard and ZigBee secrets makers take the captured text or octets as `data`, so the block rebuilds as captured from its `dict`, as from its data model ([#2698](https://github.com/JarryShaw/PyPCAPKit/issues/2698), [#2707](https://github.com/JarryShaw/PyPCAPKit/pull/2707)).
122122

‎docs/source/changelog/1.6.0.rst‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,8 @@ HTTP/1 and HTTP/2 classes under the RFC names.
238238
option parser. The registries are :mod:`pcapkit.const.dccp`, crawled from
239239
IANA. Its ``make()`` refuses a value a field cannot hold with
240240
:exc:`~pcapkit.utilities.exceptions.ProtocolError` naming the field
241-
(:issue:`2614`, :pr:`2670`).
241+
(:issue:`2614`, :pr:`2670`), and an option given as empty raw octets
242+
(:issue:`2723`, :pr:`2728`).
242243

243244
* **Added** -- :class:`~pcapkit.protocols.application.tls.TLS` (SSLv3 and TLS
244245
1.0 to 1.3) at TCP 443 and :class:`~pcapkit.protocols.application.dtls.DTLS`
@@ -1034,7 +1035,18 @@ HTTP/1 and HTTP/2 classes under the RFC names.
10341035
empty octets. The kind resolves as a ``(code, arguments)`` pair's does, so
10351036
255 builds, and empty octets raise
10361037
:exc:`~pcapkit.utilities.exceptions.ProtocolError` (:issue:`2708`,
1037-
:pr:`2724`). ``HIP(next=59)`` wrote HIP version 6, taking the IP version for
1038+
:pr:`2724`). The other makers taking a raw item refuse empty octets the same
1039+
way, as ``IPv4: invalid option: b'' holds no type octet`` (:issue:`2723`,
1040+
:pr:`2728`). IPv4's, HOPOPT's and IPv6-Opts' options raised
1041+
:exc:`IndexError`. SCTP's parameters and error causes, and MH's options,
1042+
sub-options, QoS attributes and CGA extensions, raised a bare
1043+
:exc:`AttributeError` alone -- or, for MH's access network identifier and
1044+
LMA-controlled MAG sub-options, a ``ProtocolError`` for an option of length
1045+
0 -- and were dropped beside a whole item. HIP's parameters were dropped.
1046+
PCAP-NG's options and Name Resolution records refuse octets shorter than
1047+
their 2-octet code, where 1.5.x wrote empty or zero octets as an
1048+
end-of-options or end-of-records marker, and misread one other octet as a
1049+
code. ``HIP(next=59)`` wrote HIP version 6, taking the IP version for
10381050
it, and writes 2, ``make()``'s default from :rfc:`7401#section-5.1`. HIP's
10391051
``ENCRYPTED`` maker refuses an IV given with a cipher that takes none, which
10401052
1.5.x counted in the parameter's Length but did not write. A parsed

0 commit comments

Comments
 (0)