Skip to content

Commit 94185da

Browse files
JarryShawCopilot
andauthored
feat(application): add an SSLv2 dissector (#2466)
* feat(application): add an SSLv2 dissector - SSLv2 (draft-hickman-netscape-ssl-00) subclasses SSL and joins SSL.id(). Its module and class are named SSLv2. - TLS.read tries TLS first. SSLv2 is taken only when TLS rejects the record and the payload is a complete CLIENT-HELLO or SERVER-HELLO that passes the hello length probe; anything else stays Raw. - The TLS object that adopts an SSLv2 parse reports its 2- or 3-octet header as length, so packet splits as a direct SSLv2 parse does. - TLS.from_data rebuilds an adopted SSLv2 record as SSLv2, so a port-443 hello round-trips byte-exact through TCP.from_data. - Add pcapkit.const.sslv2 (HandshakeType, Version) and bump the const census pins by +2 over #2441's. Part of #2457. * fix(tests): bump the census pins by the full +2 sslv2 adds sslv2.HandshakeType and sslv2.Version are 2 new const modules, but the branch's pin bumps were all +1. Each pinned count needed the second +1: - test_const_enum_builtin_parity: ints 118->119, enums 134->135, distinct modules 128->129 - test_const_enum_get: enums 124->125, covered 121->122 - test_const_enum_lookup: enums 118->119 - test_const_registry_protocol: all_files 128->129, generated 111->112 Verified: all four files pass clean (128 tests, 1522 subtests). * fix(vendor): add the SSLv2 crawler, DATA-attribute shape pcapkit.const.sslv2's two modules were hand-curated with no pcapkit.vendor.sslv2 crawler, violating the const-vendor-pairing rule (#2495: "ALL const MUST have its own vendor crawler... use the DATA attribute... no exception"). - Add pcapkit.vendor.sslv2 (handshake_type, version), mirroring the ARPHRD precedent (#2497): each Vendor subclass's request() returns a DATA dict transcribed from the expired SSLv2 draft (draft-hickman-netscape-ssl-00) instead of fetching a URL. - Wire SSLv2_HandshakeType and SSLv2_Version into pcapkit.vendor.__all__. - Regenerate both const modules from the crawlers. Only drift: the docstring (moved to the crawler) and Version.SSLv2's literal (0x0002 -> 2, the crawler's decimal rendering). A second run is a byte-for-byte no-op. - Bump EXPECTED_CRAWLERS_WITH_CONSTANT_MISS_LINES 35->37 for the two new crawlers. - Update docs/source/pcapkit/const/sslv2.rst and the now-stale "hand-curated, no crawler" comments in two tests. Verified: tests/vendor/, tests/const/, the sslv2-specific tests, and tests/project/test_public_api.py all green. * Merge remote-tracking branch 'origin/main' into feat/2457-sslv2-dissector Co-authored-by: JarryShaw <15666417+JarryShaw@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: JarryShaw <15666417+JarryShaw@users.noreply.github.com>
1 parent 574186e commit 94185da

37 files changed

Lines changed: 2566 additions & 34 deletions

‎docs/source/ext.rst‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -111,10 +111,12 @@ The protocol classes :mod:`pcapkit` ships:
111111
| | | :class:`pcapkit.protocols.application.ssl.SSL` |
112112
+ + +-----------------------+-------------------------------------------------------------+
113113
| | | :class:`pcapkit.protocols.application.tls.TLS` |
114-
+ + SSL Family +-----------------------+-------------------------------------------------------------+
115-
| | | :class:`pcapkit.protocols.application.tls.SSLv3` |
114+
+ + +-----------------------+-------------------------------------------------------------+
115+
| | SSL Family | :class:`pcapkit.protocols.application.tls.SSLv3` |
116116
+ + +-----------------------+-------------------------------------------------------------+
117117
| | | :class:`pcapkit.protocols.application.dtls.DTLS` |
118+
+ + +-----------------------+-------------------------------------------------------------+
119+
| | | :class:`pcapkit.protocols.application.sslv2.SSLv2` |
118120
+------------------------------------------------------------------+----------------+-----------------------+-------------------------------------------------------------+
119121
| | | :class:`pcapkit.protocols.misc.pcap.header.Header` |
120122
+ + PCAP Format +-----------------------+-------------------------------------------------------------+

‎docs/source/pcapkit/const/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,7 @@ Application Layer
107107
http
108108
ngap
109109
ospf
110+
sslv2
110111
tls
111112

112113
Miscellaneous
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
=========================================================================
2+
:class:`~pcapkit.protocols.application.sslv2.SSLv2` Constant Enumerations
3+
=========================================================================
4+
5+
.. module:: pcapkit.const.sslv2
6+
7+
This module contains all constant enumerations of
8+
:class:`~pcapkit.protocols.application.sslv2.SSLv2` implementations. Available
9+
enumerations include:
10+
11+
.. list-table::
12+
13+
* - :class:`SSLv2_HandshakeType <pcapkit.const.sslv2.handshake_type.HandshakeType>`
14+
- SSLv2 Handshake Message Type [*]_
15+
* - :class:`SSLv2_Version <pcapkit.const.sslv2.version.Version>`
16+
- SSLv2 Protocol Version [*]_
17+
18+
.. versionadded:: 1.6.0
19+
20+
SSLv2 Handshake Message Type
21+
=============================
22+
23+
.. module:: pcapkit.const.sslv2.handshake_type
24+
25+
This module contains the constant enumeration for **SSLv2 Handshake Message
26+
Type**, which is automatically generated from
27+
:class:`pcapkit.vendor.sslv2.handshake_type.HandshakeType`. Its source is the
28+
expired SSLv2 draft linked above, not a live registry, so the crawler reads a
29+
``DATA`` attribute instead of fetching a URL.
30+
31+
.. autoclass:: pcapkit.const.sslv2.handshake_type.HandshakeType
32+
:members:
33+
:undoc-members:
34+
:show-inheritance:
35+
36+
SSLv2 Protocol Version
37+
=======================
38+
39+
.. module:: pcapkit.const.sslv2.version
40+
41+
This module contains the constant enumeration for **SSLv2 Protocol
42+
Version**, which is automatically generated from
43+
:class:`pcapkit.vendor.sslv2.version.Version`, for the same reason
44+
:class:`~pcapkit.const.sslv2.handshake_type.HandshakeType` is.
45+
46+
.. autoclass:: pcapkit.const.sslv2.version.Version
47+
:members:
48+
:undoc-members:
49+
:show-inheritance:
50+
51+
.. rubric:: Footnotes
52+
53+
.. [*] https://datatracker.ietf.org/doc/html/draft-hickman-netscape-ssl-00
54+
.. [*] https://datatracker.ietf.org/doc/html/draft-hickman-netscape-ssl-00

‎docs/source/pcapkit/protocols/application/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ function rather than encapsulation, see
2323
ospf
2424
rarp
2525
ssl
26+
sslv2
2627
tls
2728
dtls
2829

‎docs/source/pcapkit/protocols/application/ssl.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ SSL - Secure Sockets Layer
88
which is the umbrella base class for the Secure Sockets Layer protocol
99
family [*]_ -- the SSL versions, Transport Layer Security and Datagram TLS:
1010

11+
* :class:`~pcapkit.protocols.application.sslv2.SSLv2` -- SSL 2.0, whose
12+
record layer shares no wire format with the others;
1113
* :class:`~pcapkit.protocols.application.tls.TLS` -- SSLv3 and TLS 1.0
1214
through TLS 1.3, with :class:`~pcapkit.protocols.application.tls.SSLv3` as
1315
its thin subclass for explicit construction;
Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
SSLv2 - Secure Sockets Layer version 2
2+
=======================================
3+
4+
.. module:: pcapkit.protocols.application.sslv2
5+
6+
:mod:`pcapkit.protocols.application.sslv2` contains
7+
:class:`~pcapkit.protocols.application.sslv2.SSLv2` only,
8+
which implements an extractor for Secure Sockets Layer
9+
version 2 (SSLv2) [*]_, whose record header is 2 or 3 octets, chosen by the
10+
high bit of its first octet (``sslv2.indicator``):
11+
12+
.. code-block:: text
13+
14+
2-octet form (high bit set):
15+
16+
0 1 2
17+
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
18+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
19+
|1| sslv2.indicator/length_low (15) |
20+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
21+
|sslv2.msg_type | handshake message body ...
22+
23+
3-octet form (high bit clear):
24+
25+
0 1 2 3
26+
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
27+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
28+
|0|E| sslv2.indicator/length_low (14) | sslv2.padding (8) |
29+
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
30+
|sslv2.msg_type | handshake message body ...
31+
32+
``E`` is the ``IS-ESCAPE`` flag, meaningful only in the 3-octet form. See
33+
:func:`~pcapkit.protocols.schema.application.sslv2.sslv2_record_length` for the
34+
exact bit arithmetic.
35+
36+
SSLv2 is wire-*incompatible* with SSLv3 and TLS: it carries no content-type
37+
byte and no ``0x03xx``-style record version, and its handshake message type
38+
is the first octet of the record's data rather than a separate record-layer
39+
field. This package parses the ``CLIENT-HELLO`` and ``SERVER-HELLO``
40+
handshake message bodies; every other
41+
:class:`~pcapkit.const.sslv2.handshake_type.HandshakeType`, and a hello-tagged
42+
body whose declared sub-field lengths do not fit the record (e.g.
43+
ciphertext), is kept as raw octets, header and message type decoded.
44+
45+
.. versionadded:: 1.6.0
46+
47+
.. raw:: html
48+
49+
<br />
50+
51+
.. autoclass:: pcapkit.protocols.application.sslv2.SSLv2
52+
:no-members:
53+
:show-inheritance:
54+
55+
.. autoproperty:: name
56+
.. autoproperty:: alias
57+
.. autoproperty:: length
58+
59+
.. automethod:: read
60+
.. automethod:: make
61+
62+
.. automethod:: id
63+
64+
.. automethod:: _make_data
65+
.. automethod:: _make_sslv2_client_hello
66+
.. automethod:: _make_sslv2_server_hello
67+
68+
Header Schemas
69+
--------------
70+
71+
.. module:: pcapkit.protocols.schema.application.sslv2
72+
73+
.. autoclass:: pcapkit.protocols.schema.application.sslv2.SSLv2
74+
:members:
75+
:show-inheritance:
76+
77+
.. autoclass:: pcapkit.protocols.schema.application.sslv2.HandshakeBody
78+
:members:
79+
:show-inheritance:
80+
81+
.. autoclass:: pcapkit.protocols.schema.application.sslv2.UnknownHandshakeBody
82+
:members:
83+
:show-inheritance:
84+
85+
.. autoclass:: pcapkit.protocols.schema.application.sslv2.ClientHello
86+
:members:
87+
:show-inheritance:
88+
89+
.. autoclass:: pcapkit.protocols.schema.application.sslv2.ServerHello
90+
:members:
91+
:show-inheritance:
92+
93+
Auxiliary Functions
94+
~~~~~~~~~~~~~~~~~~~~
95+
96+
.. autofunction:: pcapkit.protocols.schema.application.sslv2.sslv2_record_length
97+
.. autofunction:: pcapkit.protocols.schema.application.sslv2.sslv2_hello_probe_length
98+
.. autofunction:: pcapkit.protocols.schema.application.sslv2.sslv2_hello_probe_is_plausible
99+
.. autofunction:: pcapkit.protocols.schema.application.sslv2.sslv2_body_selector
100+
101+
Data Models
102+
-----------
103+
104+
.. module:: pcapkit.protocols.data.application.sslv2
105+
106+
.. autoclass:: pcapkit.protocols.data.application.sslv2.SSLv2
107+
:members:
108+
:show-inheritance:
109+
110+
.. autoclass:: pcapkit.protocols.data.application.sslv2.ClientHello
111+
:members:
112+
:show-inheritance:
113+
114+
.. autoclass:: pcapkit.protocols.data.application.sslv2.ServerHello
115+
:members:
116+
:show-inheritance:
117+
118+
.. rubric:: Footnotes
119+
120+
.. [*] https://datatracker.ietf.org/doc/html/draft-hickman-netscape-ssl-00

‎docs/source/pcapkit/protocols/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
6161
end
6262

6363
subgraph ssl [SSL Family]
64-
SSL --> TLS & DTLS
64+
SSL --> TLS & DTLS & SSLv2
6565
TLS --> SSLv3
6666
end
6767
end
@@ -182,6 +182,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
182182
click RARP "application/rarp.html#pcapkit.protocols.application.rarp.RARP"
183183
click DRARP "application/rarp.html#pcapkit.protocols.application.rarp.DRARP"
184184
click SSL "application/ssl.html#pcapkit.protocols.application.ssl.SSL"
185+
click SSLv2 "application/sslv2.html#pcapkit.protocols.application.sslv2.SSLv2"
185186
click TLS "application/tls.html#pcapkit.protocols.application.tls.TLS"
186187
click SSLv3 "application/tls.html#pcapkit.protocols.application.tls.SSLv3"
187188
click DTLS "application/dtls.html#pcapkit.protocols.application.dtls.DTLS"

‎pcapkit/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@
125125

126126
'FTP', 'FTP_DATA', # Application Layer
127127
'HTTP', 'HTTPv1', 'HTTPv2', 'NGAP', 'OSPF',
128-
'RARP', 'DRARP', 'SSL', 'SSLv3', 'TLS', 'DTLS',
128+
'RARP', 'DRARP', 'SSL', 'SSLv2', 'SSLv3', 'TLS', 'DTLS',
129129

130130
'Data', # Protocol Data
131131
'Schema', # Protocol Schema

‎pcapkit/all.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@
132132
'TCP', 'UDP', 'SCTP', # Transport Layer
133133
'FTP', 'FTP_DATA', # Application Layer
134134
'HTTP', 'HTTPv1', 'HTTPv2', 'NGAP', 'OSPF', 'RARP', 'DRARP',
135-
'SSL', 'SSLv3', 'TLS', 'DTLS',
135+
'SSL', 'SSLv2', 'SSLv3', 'TLS', 'DTLS',
136136
'Schema', 'schema', # Protocol Schema
137137
'Data', 'data', # Protocol Data
138138

‎pcapkit/const/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
from pcapkit.const.ngap import *
3232
from pcapkit.const.ospf import *
3333
from pcapkit.const.sctp import *
34+
from pcapkit.const.sslv2 import *
3435
from pcapkit.const.tcp import *
3536
from pcapkit.const.tls import *
3637
from pcapkit.const.vlan import *
@@ -90,6 +91,8 @@
9091
'OSPF_Authentication', 'OSPF_Packet',
9192
# SCTP
9293
'SCTP_Chunk', 'SCTP_Parameter', 'SCTP_CauseCode', 'SCTP_PayloadProtocolIdentifier',
94+
# SSLv2
95+
'SSLv2_HandshakeType', 'SSLv2_Version',
9396
# TCP
9497
'TCP_Checksum', 'TCP_Option', 'TCP_MPTCPOption', 'TCP_Flags',
9598
# TLS/DTLS

0 commit comments

Comments
 (0)