Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 29 additions & 8 deletions docs/source/contributing/pep.rst
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ the ones outstanding are,

* Link Layer: DSL, EAPOL, FDDI, ISDN, NDP, PPP
* Internet Layer: ECN, Shim6
* Transport Layer: DCCP, RSVP
* Transport Layer: RSVP
* Application Layer: BGP, DHCP, DHCPv6, DNS, IMAP, LDAP, MQTT, NNTP,
NTP, ONC/RPC, POP, QUIC, RIP, RTP, SIP, SMTP, SNMP, SSH, Telnet,
XMPP
Expand Down Expand Up @@ -818,12 +818,13 @@ These protocols parse a checksum or CRC field —
:class:`~pcapkit.protocols.internet.ipx.IPX`,
:class:`~pcapkit.protocols.internet.mh.MH`,
:class:`~pcapkit.protocols.application.ospf.OSPF`,
:class:`~pcapkit.protocols.transport.dccp.DCCP`,
:class:`~pcapkit.protocols.transport.sctp.SCTP`,
:class:`~pcapkit.protocols.transport.tcp.TCP` and
:class:`~pcapkit.protocols.transport.udp.UDP` — and SCTP was the first to
check whether the value is *right*, through
:attr:`SCTP.checksum_valid <pcapkit.protocols.transport.sctp.SCTP.checksum_valid>`.
IPv4, OSPF, TCP and UDP check it too, as do ICMP and ICMPv6, as the
IPv4, OSPF, TCP, UDP and DCCP check it too, as do ICMP and ICMPv6, as the
one's-complement half below describes. For HIP, HOPOPT, IPv6-Opts, IPX and MH the
field is recorded and never questioned, so a corrupted capture parses as cleanly
as an intact one.
Expand All @@ -832,9 +833,9 @@ as an intact one.
of them is cryptographic and the distinction decides what is actually hard.

**The one's-complement Internet checksum**, which covers IPv4's header, TCP, UDP,
ICMP/ICMPv6 and OSPF, needs no cryptography at all — it is sixteen-bit addition
DCCP, ICMP/ICMPv6 and OSPF, needs no cryptography at all — it is sixteen-bit addition
with end-around carry, and implementing it is an afternoon. What blocks it is the
**IP pseudo-header**: the TCP, UDP and ICMPv6 checksums are computed over source
**IP pseudo-header**: the TCP, UDP, DCCP and ICMPv6 checksums are computed over source
and destination addresses, the protocol number and the payload length, all of
which live in the *enclosing* layer. So verification needs a parsed protocol to
reach back to its parent, which is a structural question about
Expand Down Expand Up @@ -924,6 +925,20 @@ offload heuristic on :issue:`2470`.
checksum covers, so it is verified when the fragment holds that much, and
:attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.TRUNCATED`
otherwise.
* **DCCP covers what its Checksum Coverage gives** (:rfc:`4340#section-9.2`), over
a pseudo-header that carries the whole packet's length, as TCP's does, so a
fragment is
:attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.NO_PSEUDO_HEADER`
too. A coverage running past the packet, which the RFC forbids and has the
receiver ignore, is
:attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.INVALID` and
warns. Linux, until it dropped DCCP in 6.16, never sent one: its
``dccp_csum_outgoing`` wrote a CsCov of 0 wherever the coverage reached the
end of the packet, and ``make()`` does the same when it computes the
checksum. No value is
:attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.NOT_COMPUTED`:
DCCP has no checksum to leave out, and Linux computed it in software rather
than offloading it. Settled at implementation (:issue:`2489`).

The cryptographic half is sequenced for **wave 2 or 3**, and could be done sooner
since ESP has already laid the groundwork.
Expand Down Expand Up @@ -1123,9 +1138,15 @@ Steps`_ above.
**Wave 2 — the protocol pairs that want a shared abstract base**, per `More
Protocols, More!!!`_ above: **TLS/SSL with DTLS** and **IGMP** and **DCCP** on
their own. These are grouped because the shared-base question is the design work
and doing either half of a pair alone would answer it twice. **DCCP** is the
transport-layer implementation, tracked by :issue:`2489`, and blocked on
:issue:`2479` for its pseudo-header checksum.
and doing either half of a pair alone would answer it twice.

**DCCP — done within wave 2** (:issue:`2489`).
:class:`~pcapkit.protocols.transport.dccp.DCCP` dissects every :rfc:`4340` packet
type and DCCP-Listen (:rfc:`5596`), with short and long sequence numbers, and the
options :rfc:`4340` defines; its checksum is verified and computed over
:class:`~pcapkit.protocols.misc.checksum.ip_pseudo.IP_Pseudo`, as `Checksum and
Integrity Verification`_ above describes. The Data Checksum option's CRC-32c is
recorded and not checked.

**Done within wave 2 — ICMP/ICMPv6 shared base.** :class:`~pcapkit.protocols.internet.icmp.ICMP`
is the abstract base :class:`~pcapkit.protocols.internet.icmpv4.ICMPv4` and
Expand Down Expand Up @@ -1311,7 +1332,7 @@ and its signature parameters could start whenever, since
:class:`~pcapkit.protocols.internet.esp.ESP` has already established both the
keying-context channel and the report-rather-than-raise policy. The
one's-complement half (IPv4, TCP, UDP, ICMP/ICMPv6, OSPF) is **done**
(:issue:`2470`, :issue:`2472` to :issue:`2475`).
(:issue:`2470`, :issue:`2472` to :issue:`2475`), and DCCP's with it (:issue:`2489`).

**IP pseudo-header — done** (:issue:`2471`).
:class:`~pcapkit.protocols.misc.checksum.ip_pseudo.IP_Pseudo` is the
Expand Down
6 changes: 6 additions & 0 deletions docs/source/ext.rst
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,8 @@ The protocol classes :mod:`pcapkit` ships:
| subclasses) | :class:`pcapkit.protocols.transport.udp.UDP` |
+ +----------------+-----------------------+-------------------------------------------------------------+
| | :class:`pcapkit.protocols.transport.sctp.SCTP` |
+ +----------------+-----------------------+-------------------------------------------------------------+
| | :class:`pcapkit.protocols.transport.dccp.DCCP` |
+------------------------------------------------------------------+----------------+-----------------------+-------------------------------------------------------------+
| | | :class:`pcapkit.protocols.application.ftp.FTP` |
+ + FTP Family +-----------------------+-------------------------------------------------------------+
Expand Down Expand Up @@ -194,6 +196,8 @@ The registry function per protocol type:
| | | :func:`~pcapkit.foundation.registry.protocols.register_udp` | new protocols. |
+ +-------------------------------------------------------------------+----------------------------------------------------------------+ +
| | | :func:`~pcapkit.foundation.registry.protocols.register_sctp` | |
+ +-------------------------------------------------------------------+----------------------------------------------------------------+ +
| | | :func:`~pcapkit.foundation.registry.protocols.register_dccp` | |
+-------------------+-------------------------------------------------------------------+----------------------------------------------------------------+--------------------+

A protocol carried over IPX is keyed by IPX Packet Type rather than by IP protocol
Expand Down Expand Up @@ -405,6 +409,8 @@ writes them:
| | :class:`~pcapkit.protocols.transport.sctp.SCTP` | :attr:`SCTP.__parameter__ <pcapkit.protocols.transport.sctp.SCTP.__parameter__>` | :func:`~pcapkit.foundation.registry.protocols.register_sctp_parameter` |
+ + +-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
| | | :attr:`SCTP.__cause__ <pcapkit.protocols.transport.sctp.SCTP.__cause__>` | :func:`~pcapkit.foundation.registry.protocols.register_sctp_cause` |
+ +------------------------------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
| | :class:`~pcapkit.protocols.transport.dccp.DCCP` | :attr:`DCCP.__option__ <pcapkit.protocols.transport.dccp.DCCP.__option__>` | :func:`~pcapkit.foundation.registry.protocols.register_dccp_option` |
+-------------------+------------------------------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
| Application Layer | :class:`~pcapkit.protocols.application.httpv2.HTTPv2` | :attr:`HTTPv2.__frame__ <pcapkit.protocols.application.httpv2.HTTPv2.__frame__>` | :func:`~pcapkit.foundation.registry.protocols.register_http_frame` |
+-------------------+------------------------------------------------------------+-----------------------------------------------------------------------------------------------+----------------------------------------------------------------------------+
Expand Down
111 changes: 111 additions & 0 deletions docs/source/pcapkit/const/dccp.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
=====================================================================
:class:`~pcapkit.protocols.transport.dccp.DCCP` Constant Enumerations
=====================================================================

.. module:: pcapkit.const.dccp

This module contains all constant enumerations of
:class:`~pcapkit.protocols.transport.dccp.DCCP` implementations. Available
enumerations include:

.. list-table::

* - :class:`DCCP_PacketType <pcapkit.const.dccp.packet_type.PacketType>`
- DCCP Packet Types [*]_
* - :class:`DCCP_ResetCode <pcapkit.const.dccp.reset_code.ResetCode>`
- DCCP Reset Codes [*]_
* - :class:`DCCP_Option <pcapkit.const.dccp.option.Option>`
- DCCP Option Types [*]_
* - :class:`DCCP_Feature <pcapkit.const.dccp.feature.Feature>`
- DCCP Feature Numbers [*]_
* - :class:`DCCP_AckVectorState <pcapkit.const.dccp.ack_vector_state.AckVectorState>`
- DCCP Ack Vector States [*]_
* - :class:`DCCP_DropCode <pcapkit.const.dccp.drop_code.DropCode>`
- DCCP Drop Codes [*]_

DCCP Packet Types
=================

.. module:: pcapkit.const.dccp.packet_type

This module contains the constant enumeration for **DCCP Packet Types**,
which is automatically generated from :class:`pcapkit.vendor.dccp.packet_type.PacketType`.

.. autoclass:: pcapkit.const.dccp.packet_type.PacketType
:members:
:undoc-members:
:show-inheritance:

DCCP Reset Codes
================

.. module:: pcapkit.const.dccp.reset_code

This module contains the constant enumeration for **DCCP Reset Codes**,
which is automatically generated from :class:`pcapkit.vendor.dccp.reset_code.ResetCode`.

.. autoclass:: pcapkit.const.dccp.reset_code.ResetCode
:members:
:undoc-members:
:show-inheritance:

DCCP Option Types
=================

.. module:: pcapkit.const.dccp.option

This module contains the constant enumeration for **DCCP Option Types**,
which is automatically generated from :class:`pcapkit.vendor.dccp.option.Option`.

.. autoclass:: pcapkit.const.dccp.option.Option
:members:
:undoc-members:
:show-inheritance:

DCCP Feature Numbers
====================

.. module:: pcapkit.const.dccp.feature

This module contains the constant enumeration for **DCCP Feature Numbers**,
which is automatically generated from :class:`pcapkit.vendor.dccp.feature.Feature`.

.. autoclass:: pcapkit.const.dccp.feature.Feature
:members:
:undoc-members:
:show-inheritance:

DCCP Ack Vector States
======================

.. module:: pcapkit.const.dccp.ack_vector_state

This module contains the constant enumeration for **DCCP Ack Vector States**,
which is automatically generated from :class:`pcapkit.vendor.dccp.ack_vector_state.AckVectorState`.

.. autoclass:: pcapkit.const.dccp.ack_vector_state.AckVectorState
:members:
:undoc-members:
:show-inheritance:

DCCP Drop Codes
===============

.. module:: pcapkit.const.dccp.drop_code

This module contains the constant enumeration for **DCCP Drop Codes**,
which is automatically generated from :class:`pcapkit.vendor.dccp.drop_code.DropCode`.

.. autoclass:: pcapkit.const.dccp.drop_code.DropCode
:members:
:undoc-members:
:show-inheritance:

.. rubric:: Footnotes

.. [*] https://www.iana.org/assignments/dccp-parameters/dccp-parameters.xhtml#dccp-parameters-1
.. [*] https://www.iana.org/assignments/dccp-parameters/dccp-parameters.xhtml#dccp-parameters-3
.. [*] https://www.iana.org/assignments/dccp-parameters/dccp-parameters.xhtml#dccp-parameters-5
.. [*] https://www.iana.org/assignments/dccp-parameters/dccp-parameters.xhtml#dccp-parameters-7
.. [*] https://www.iana.org/assignments/dccp-parameters/dccp-parameters.xhtml#dccp-parameters-10
.. [*] https://www.iana.org/assignments/dccp-parameters/dccp-parameters.xhtml#dccp-parameters-11
1 change: 1 addition & 0 deletions docs/source/pcapkit/const/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,7 @@ Transport Layer
.. toctree::
:maxdepth: 2

dccp
sctp
tcp

Expand Down
4 changes: 4 additions & 0 deletions docs/source/pcapkit/foundation/registry.rst
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,10 @@ Transport Layer Registries

.. autofunction:: pcapkit.foundation.registry.protocols.register_sctp_cause

.. autofunction:: pcapkit.foundation.registry.protocols.register_dccp

.. autofunction:: pcapkit.foundation.registry.protocols.register_dccp_option

Application Layer Registries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
3 changes: 2 additions & 1 deletion docs/source/pcapkit/protocols/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
end

subgraph transport [Transport Layer]
Transport --> TCP & UDP & SCTP
Transport --> TCP & UDP & SCTP & DCCP
end

B --> Link & Internet & Transport & Application
Expand Down Expand Up @@ -171,6 +171,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
click TCP "transport/tcp.html#pcapkit.protocols.transport.tcp.TCP"
click UDP "transport/udp.html#pcapkit.protocols.transport.udp.UDP"
click SCTP "transport/sctp.html#pcapkit.protocols.transport.sctp.SCTP"
click DCCP "transport/dccp.html#pcapkit.protocols.transport.dccp.DCCP"

click Application "application/application.html#pcapkit.protocols.application.application.Application"
click HTTP "application/http.html#pcapkit.protocols.application.http.HTTP"
Expand Down
Loading
Loading