feat(application): add an SSLv2 dissector

docs/source/ext.rst

@@ -111,10 +111,12 @@ The protocol classes :mod:`pcapkit` ships:
 |                                                                  |                | :class:`pcapkit.protocols.application.ssl.SSL`                                      |
 +                                                                  +                +-----------------------+-------------------------------------------------------------+
 |                                                                  |                | :class:`pcapkit.protocols.application.tls.TLS`                                      |
-+                                                                  + SSL Family     +-----------------------+-------------------------------------------------------------+
-|                                                                  |                | :class:`pcapkit.protocols.application.tls.SSLv3`                                    |
++                                                                  +                +-----------------------+-------------------------------------------------------------+
+|                                                                  | SSL Family     | :class:`pcapkit.protocols.application.tls.SSLv3`                                    |
 +                                                                  +                +-----------------------+-------------------------------------------------------------+
 |                                                                  |                | :class:`pcapkit.protocols.application.dtls.DTLS`                                    |
++                                                                  +                +-----------------------+-------------------------------------------------------------+
+|                                                                  |                | :class:`pcapkit.protocols.application.sslv2.SSLv2`                                  |
 +------------------------------------------------------------------+----------------+-----------------------+-------------------------------------------------------------+
 |                                                                  |                | :class:`pcapkit.protocols.misc.pcap.header.Header`                                  |
 +                                                                  + PCAP Format    +-----------------------+-------------------------------------------------------------+

docs/source/pcapkit/const/index.rst

@@ -107,6 +107,7 @@ Application Layer
    http
    ngap
    ospf
+   sslv2
    tls
 
 Miscellaneous

docs/source/pcapkit/const/sslv2.rst

@@ -0,0 +1,54 @@
+=========================================================================
+:class:`~pcapkit.protocols.application.sslv2.SSLv2` Constant Enumerations
+=========================================================================
+
+.. module:: pcapkit.const.sslv2
+
+This module contains all constant enumerations of
+:class:`~pcapkit.protocols.application.sslv2.SSLv2` implementations. Available
+enumerations include:
+
+.. list-table::
+
+   * - :class:`SSLv2_HandshakeType <pcapkit.const.sslv2.handshake_type.HandshakeType>`
+     - SSLv2 Handshake Message Type [*]_
+   * - :class:`SSLv2_Version <pcapkit.const.sslv2.version.Version>`
+     - SSLv2 Protocol Version [*]_
+
+.. versionadded:: 1.6.0
+
+SSLv2 Handshake Message Type
+=============================
+
+.. module:: pcapkit.const.sslv2.handshake_type
+
+This module contains the constant enumeration for **SSLv2 Handshake Message
+Type**, which is automatically generated from
+:class:`pcapkit.vendor.sslv2.handshake_type.HandshakeType`. Its source is the
+expired SSLv2 draft linked above, not a live registry, so the crawler reads a
+``DATA`` attribute instead of fetching a URL.
+
+.. autoclass:: pcapkit.const.sslv2.handshake_type.HandshakeType
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+SSLv2 Protocol Version
+=======================
+
+.. module:: pcapkit.const.sslv2.version
+
+This module contains the constant enumeration for **SSLv2 Protocol
+Version**, which is automatically generated from
+:class:`pcapkit.vendor.sslv2.version.Version`, for the same reason
+:class:`~pcapkit.const.sslv2.handshake_type.HandshakeType` is.
+
+.. autoclass:: pcapkit.const.sslv2.version.Version
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. rubric:: Footnotes
+
+.. [*] https://datatracker.ietf.org/doc/html/draft-hickman-netscape-ssl-00
+.. [*] https://datatracker.ietf.org/doc/html/draft-hickman-netscape-ssl-00

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

@@ -23,6 +23,7 @@ function rather than encapsulation, see
    ospf
    rarp
    ssl
+   sslv2
    tls
    dtls
 

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

@@ -8,6 +8,8 @@ SSL - Secure Sockets Layer
 which is the umbrella base class for the Secure Sockets Layer protocol
 family [*]_ -- the SSL versions, Transport Layer Security and Datagram TLS:
 
+* :class:`~pcapkit.protocols.application.sslv2.SSLv2` -- SSL 2.0, whose
+  record layer shares no wire format with the others;
 * :class:`~pcapkit.protocols.application.tls.TLS` -- SSLv3 and TLS 1.0
   through TLS 1.3, with :class:`~pcapkit.protocols.application.tls.SSLv3` as
   its thin subclass for explicit construction;

docs/source/pcapkit/protocols/application/sslv2.rst

@@ -0,0 +1,120 @@
+SSLv2 - Secure Sockets Layer version 2
+=======================================
+
+.. module:: pcapkit.protocols.application.sslv2
+
+:mod:`pcapkit.protocols.application.sslv2` contains
+:class:`~pcapkit.protocols.application.sslv2.SSLv2` only,
+which implements an extractor for Secure Sockets Layer
+version 2 (SSLv2) [*]_, whose record header is 2 or 3 octets, chosen by the
+high bit of its first octet (``sslv2.indicator``):
+
+.. code-block:: text
+
+   2-octet form (high bit set):
+
+      0                   1                   2
+      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+     |1|      sslv2.indicator/length_low (15)    |
+     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+     |sslv2.msg_type |   handshake message body ...
+
+   3-octet form (high bit clear):
+
+      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
+     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+     |0|E|   sslv2.indicator/length_low (14)  |  sslv2.padding (8)   |
+     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+     |sslv2.msg_type |   handshake message body ...
+
+``E`` is the ``IS-ESCAPE`` flag, meaningful only in the 3-octet form. See
+:func:`~pcapkit.protocols.schema.application.sslv2.sslv2_record_length` for the
+exact bit arithmetic.
+
+SSLv2 is wire-*incompatible* with SSLv3 and TLS: it carries no content-type
+byte and no ``0x03xx``-style record version, and its handshake message type
+is the first octet of the record's data rather than a separate record-layer
+field. This package parses the ``CLIENT-HELLO`` and ``SERVER-HELLO``
+handshake message bodies; every other
+:class:`~pcapkit.const.sslv2.handshake_type.HandshakeType`, and a hello-tagged
+body whose declared sub-field lengths do not fit the record (e.g.
+ciphertext), is kept as raw octets, header and message type decoded.
+
+.. versionadded:: 1.6.0
+
+.. raw:: html
+
+   <br />
+
+.. autoclass:: pcapkit.protocols.application.sslv2.SSLv2
+   :no-members:
+   :show-inheritance:
+
+   .. autoproperty:: name
+   .. autoproperty:: alias
+   .. autoproperty:: length
+
+   .. automethod:: read
+   .. automethod:: make
+
+   .. automethod:: id
+
+   .. automethod:: _make_data
+   .. automethod:: _make_sslv2_client_hello
+   .. automethod:: _make_sslv2_server_hello
+
+Header Schemas
+--------------
+
+.. module:: pcapkit.protocols.schema.application.sslv2
+
+.. autoclass:: pcapkit.protocols.schema.application.sslv2.SSLv2
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.protocols.schema.application.sslv2.HandshakeBody
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.protocols.schema.application.sslv2.UnknownHandshakeBody
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.protocols.schema.application.sslv2.ClientHello
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.protocols.schema.application.sslv2.ServerHello
+   :members:
+   :show-inheritance:
+
+Auxiliary Functions
+~~~~~~~~~~~~~~~~~~~~
+
+.. autofunction:: pcapkit.protocols.schema.application.sslv2.sslv2_record_length
+.. autofunction:: pcapkit.protocols.schema.application.sslv2.sslv2_hello_probe_length
+.. autofunction:: pcapkit.protocols.schema.application.sslv2.sslv2_hello_probe_is_plausible
+.. autofunction:: pcapkit.protocols.schema.application.sslv2.sslv2_body_selector
+
+Data Models
+-----------
+
+.. module:: pcapkit.protocols.data.application.sslv2
+
+.. autoclass:: pcapkit.protocols.data.application.sslv2.SSLv2
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.protocols.data.application.sslv2.ClientHello
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pcapkit.protocols.data.application.sslv2.ServerHello
+   :members:
+   :show-inheritance:
+
+.. rubric:: Footnotes
+
+.. [*] https://datatracker.ietf.org/doc/html/draft-hickman-netscape-ssl-00

docs/source/pcapkit/protocols/index.rst

@@ -61,7 +61,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
            end
 
            subgraph ssl [SSL Family]
-               SSL --> TLS & DTLS
+               SSL --> TLS & DTLS & SSLv2
                TLS --> SSLv3
            end
        end
@@ -182,6 +182,7 @@ from given information. The class hierarchy of :mod:`pcapkit.protocols`:
        click RARP "application/rarp.html#pcapkit.protocols.application.rarp.RARP"
        click DRARP "application/rarp.html#pcapkit.protocols.application.rarp.DRARP"
        click SSL "application/ssl.html#pcapkit.protocols.application.ssl.SSL"
+       click SSLv2 "application/sslv2.html#pcapkit.protocols.application.sslv2.SSLv2"
        click TLS "application/tls.html#pcapkit.protocols.application.tls.TLS"
        click SSLv3 "application/tls.html#pcapkit.protocols.application.tls.SSLv3"
        click DTLS "application/dtls.html#pcapkit.protocols.application.dtls.DTLS"

pcapkit/__init__.py

@@ -125,7 +125,7 @@
 
     'FTP', 'FTP_DATA',                                      # Application Layer
     'HTTP', 'HTTPv1', 'HTTPv2', 'NGAP', 'OSPF',
-    'RARP', 'DRARP', 'SSL', 'SSLv3', 'TLS', 'DTLS',
+    'RARP', 'DRARP', 'SSL', 'SSLv2', 'SSLv3', 'TLS', 'DTLS',
 
     'Data',                                                 # Protocol Data
     'Schema',                                               # Protocol Schema

pcapkit/all.py

@@ -132,7 +132,7 @@
     'TCP', 'UDP', 'SCTP',                                   # Transport Layer
     'FTP', 'FTP_DATA',                                      # Application Layer
     'HTTP', 'HTTPv1', 'HTTPv2', 'NGAP', 'OSPF', 'RARP', 'DRARP',
-    'SSL', 'SSLv3', 'TLS', 'DTLS',
+    'SSL', 'SSLv2', 'SSLv3', 'TLS', 'DTLS',
     'Schema', 'schema',                                     # Protocol Schema
     'Data', 'data',                                         # Protocol Data
 

pcapkit/const/__init__.py

@@ -31,6 +31,7 @@
 from pcapkit.const.ngap import *
 from pcapkit.const.ospf import *
 from pcapkit.const.sctp import *
+from pcapkit.const.sslv2 import *
 from pcapkit.const.tcp import *
 from pcapkit.const.tls import *
 from pcapkit.const.vlan import *
@@ -90,6 +91,8 @@
     'OSPF_Authentication', 'OSPF_Packet',
     # SCTP
     'SCTP_Chunk', 'SCTP_Parameter', 'SCTP_CauseCode', 'SCTP_PayloadProtocolIdentifier',
+    # SSLv2
+    'SSLv2_HandshakeType', 'SSLv2_Version',
     # TCP
     'TCP_Checksum', 'TCP_Option', 'TCP_MPTCPOption', 'TCP_Flags',
     # TLS/DTLS

pcapkit/const/sslv2/__init__.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=unused-import
+r""":class:`~pcapkit.protocols.application.sslv2.SSLv2` Constant Enumerations
+=============================================================================
+
+.. module:: pcapkit.const.sslv2
+
+This module contains all constant enumerations of
+:class:`~pcapkit.protocols.application.sslv2.SSLv2` implementations. Available
+enumerations include:
+
+.. list-table::
+
+   * - :class:`SSLv2_HandshakeType <pcapkit.const.sslv2.handshake_type.HandshakeType>`
+     - SSLv2 Handshake Message Type [*]_
+   * - :class:`SSLv2_Version <pcapkit.const.sslv2.version.Version>`
+     - SSLv2 Protocol Version [*]_
+
+.. [*] https://datatracker.ietf.org/doc/html/draft-hickman-netscape-ssl-00
+.. [*] https://datatracker.ietf.org/doc/html/draft-hickman-netscape-ssl-00
+
+"""
+
+from pcapkit.const.sslv2.handshake_type import HandshakeType as SSLv2_HandshakeType
+from pcapkit.const.sslv2.version import Version as SSLv2_Version
+
+__all__ = ['SSLv2_HandshakeType', 'SSLv2_Version']

pcapkit/const/sslv2/handshake_type.py

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=line-too-long,consider-using-f-string
+"""SSLv2 Handshake Message Type
+==================================
+
+.. module:: pcapkit.const.sslv2.handshake_type
+
+This module contains the constant enumeration for **SSLv2 Handshake Message Type**,
+which is automatically generated from :class:`pcapkit.vendor.sslv2.handshake_type.HandshakeType`.
+
+"""
+
+from typing import TYPE_CHECKING
+
+from aenum import IntEnum
+
+from pcapkit.corekit.enum import EnumRegistry
+from pcapkit.utilities.exceptions import EnumValueError
+
+if TYPE_CHECKING:
+    from typing import Any
+
+__all__ = ['HandshakeType']
+
+
+class HandshakeType(EnumRegistry, IntEnum):
+    """[HandshakeType] SSLv2 Handshake Message Type"""
+
+    #: ``MSG-ERROR``
+    ERROR = 0
+
+    #: ``MSG-CLIENT-HELLO``
+    CLIENT_HELLO = 1
+
+    #: ``MSG-CLIENT-MASTER-KEY``
+    CLIENT_MASTER_KEY = 2
+
+    #: ``MSG-CLIENT-FINISHED``
+    CLIENT_FINISHED = 3
+
+    #: ``MSG-SERVER-HELLO``
+    SERVER_HELLO = 4
+
+    #: ``MSG-SERVER-VERIFY``
+    SERVER_VERIFY = 5
+
+    #: ``MSG-SERVER-FINISHED``
+    SERVER_FINISHED = 6
+
+    #: ``MSG-REQUEST-CERTIFICATE``
+    REQUEST_CERTIFICATE = 7
+
+    #: ``MSG-CLIENT-CERTIFICATE``
+    CLIENT_CERTIFICATE = 8
+
+    @classmethod
+    def _validate_value(cls, value: 'Any') -> 'None':
+        """Reject ``value`` unless it passes the range check :meth:`_missing_` makes.
+
+        Overrides :meth:`~pcapkit.corekit.enum.EnumLookup._validate_value`
+        with that check and the message it raises, so
+        :meth:`~pcapkit.corekit.enum.EnumRegistry.register` refuses exactly the
+        values :meth:`~pcapkit.corekit.enum.EnumLookup.get` refuses, in the
+        same words (:issue:`1816`).
+
+        Args:
+            value: Value about to be looked up or minted.
+
+        Raises:
+            EnumValueError: If ``value`` fails that check. A
+                :exc:`ValueError`, so an ``except ValueError`` caller is
+                unaffected.
+
+        """
+        if not (isinstance(value, int) and 0x00 <= value <= 0xFF):
+            raise EnumValueError('%r is not a valid %s' % (value, cls.__name__))
+
+    @classmethod
+    def _missing_(cls, value: 'int') -> 'HandshakeType':
+        """Lookup function used when value is not found.
+
+        Args:
+            value: Value to get enum item.
+
+        """
+        if not (isinstance(value, int) and 0x00 <= value <= 0xFF):
+            raise ValueError('%r is not a valid %s' % (value, cls.__name__))
+        return cls._unregistered_member(value, 'Unassigned')