ssl2 1.0.0__py3-none-any.whl

ssl2/__init__.py

@@ -0,0 +1,106 @@
+from ssl2.asynchronous import AsyncTransport, StreamTransport, TLSStream
+from ssl2.client_hello import ClientHello, ClientHelloBuilder, ClientHelloParser
+from ssl2.credentials import (
+    Certificate,
+    Credential,
+    PrivateKey,
+    SigningChain,
+    TrustStore,
+)
+from ssl2.errors import (
+    ConfigurationError,
+    EarlyDataRejected,
+    RaggedEOF,
+    TLSError,
+    WantReadError,
+    WantWriteError,
+)
+from ssl2.fingerprint import (
+    JA3,
+    JA4,
+    AkamaiFingerprint,
+    Http2Priority,
+    Http2Setting,
+    JA4Transport,
+    JA4Version,
+    PseudoHeader,
+)
+from ssl2.interface import (
+    ClientContext,
+    ServerContext,
+    SessionCache,
+    TLSBuffer,
+    TLSClientConfiguration,
+    TLSImplementation,
+    TLSServerConfiguration,
+    TLSSocket,
+    Transport,
+)
+from ssl2.parameters import (
+    CertificateCompressionAlgorithm,
+    CipherSuite,
+    CodePoint,
+    ECPointFormat,
+    ExtensionType,
+    Http2SettingIdentifier,
+    NamedGroup,
+    NextProtocol,
+    ProtocolVersion,
+    PskKeyExchangeMode,
+    SignatureScheme,
+    TLSVersion,
+)
+from ssl2.proxy import Proxy, ProxyCredentials, ProxyError, ProxyScheme
+
+__all__ = (
+    "JA3",
+    "JA4",
+    "AkamaiFingerprint",
+    "AsyncTransport",
+    "Certificate",
+    "CertificateCompressionAlgorithm",
+    "CipherSuite",
+    "ClientContext",
+    "ClientHello",
+    "ClientHelloBuilder",
+    "ClientHelloParser",
+    "CodePoint",
+    "ConfigurationError",
+    "Credential",
+    "ECPointFormat",
+    "EarlyDataRejected",
+    "ExtensionType",
+    "Http2Priority",
+    "Http2Setting",
+    "Http2SettingIdentifier",
+    "JA4Transport",
+    "JA4Version",
+    "NamedGroup",
+    "NextProtocol",
+    "PrivateKey",
+    "ProtocolVersion",
+    "Proxy",
+    "ProxyCredentials",
+    "ProxyError",
+    "ProxyScheme",
+    "PseudoHeader",
+    "PskKeyExchangeMode",
+    "RaggedEOF",
+    "ServerContext",
+    "SessionCache",
+    "SignatureScheme",
+    "SigningChain",
+    "StreamTransport",
+    "TLSBuffer",
+    "TLSClientConfiguration",
+    "TLSError",
+    "TLSImplementation",
+    "TLSServerConfiguration",
+    "TLSSocket",
+    "TLSStream",
+    "TLSVersion",
+    "Transport",
+    "TrustStore",
+    "WantReadError",
+    "WantWriteError",
+)

ssl2/asynchronous.py

@@ -0,0 +1,217 @@
+import asyncio
+import socket
+from collections.abc import Callable, Generator
+from functools import partial
+from typing import Final, Protocol, Self, cast, final
+
+from ssl2.errors import RaggedEOF, WantReadError, WantWriteError
+from ssl2.interface import RECEIVE_SIZE, ClientContext, ServerContext, TLSBuffer
+from ssl2.parameters import CipherSuite, NextProtocol, TLSVersion
+from ssl2.proxy import Proxy, ProxyError, ProxyScheme
+
+SHUTDOWN_TIMEOUT: Final = 5.0
+
+
+class AsyncTransport(Protocol):
+    async def read(self, limit: int, /) -> bytes: ...
+
+    async def write(self, data: bytes, /) -> None: ...
+
+    async def close(self) -> None: ...
+
+
+@final
+class StreamTransport:
+    def __init__(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        self._reader = reader
+        self._writer = writer
+
+    async def read(self, limit: int) -> bytes:
+        return await self._reader.read(limit)
+
+    async def write(self, data: bytes) -> None:
+        self._writer.write(data)
+        await self._writer.drain()
+
+    async def close(self) -> None:
+        self._writer.close()
+
+
+@final
+class TLSStream:
+    def __init__(
+        self,
+        context: ClientContext | ServerContext,
+        buffer: TLSBuffer,
+        transport: AsyncTransport,
+    ) -> None:
+        self._context = context
+        self._buffer = buffer
+        self._transport = transport
+
+    @classmethod
+    async def connect(
+        cls,
+        context: ClientContext,
+        address: tuple[str, int],
+        *,
+        proxy: Proxy | None = None,
+        timeout: float | None = None,
+    ) -> Self:
+        async with asyncio.timeout(timeout):
+            transport, leftover = await cls.tunnel(context, address, proxy)
+            try:
+                return await cls.open(
+                    context, context.create_buffer(address[0]), transport, leftover
+                )
+            except BaseException:
+                await transport.close()
+                raise
+
+    @classmethod
+    async def tunnel(
+        cls, context: ClientContext, address: tuple[str, int], proxy: Proxy | None
+    ) -> tuple[AsyncTransport, bytes]:
+        if proxy is None:
+            return StreamTransport(*await asyncio.open_connection(*address)), b""
+        transport: AsyncTransport
+        if proxy.scheme is ProxyScheme.HTTPS:
+            transport = await cls.connect(context, (proxy.host, proxy.port))
+        else:
+            transport = StreamTransport(
+                *await asyncio.open_connection(proxy.host, proxy.port)
+            )
+        try:
+            return transport, await cls._tunnel(proxy, address, transport)
+        except BaseException:
+            await transport.close()
+            raise
+
+    @classmethod
+    async def open(
+        cls,
+        context: ClientContext | ServerContext,
+        buffer: TLSBuffer,
+        transport: AsyncTransport,
+        leftover: bytes = b"",
+    ) -> Self:
+        self = cls(context, buffer, transport)
+        if leftover:
+            buffer.process_incoming(leftover)
+        await self._run(buffer.do_handshake)
+        return self
+
+    @property
+    def context(self) -> ClientContext | ServerContext:
+        return self._context
+
+    @property
+    def buffer(self) -> TLSBuffer:
+        return self._buffer
+
+    async def read(self, limit: int) -> bytes:
+        try:
+            return await self._run(lambda: self._buffer.read(limit))
+        except RaggedEOF:
+            return b""
+
+    async def write(self, data: bytes) -> None:
+        view = memoryview(data)
+        while view:
+            written = await self._run(partial(self._buffer.write, view))
+            view = view[written:]
+
+    async def close(self) -> None:
+        try:
+            async with asyncio.timeout(SHUTDOWN_TIMEOUT):
+                await self._run(self._buffer.shutdown)
+        except TimeoutError, RaggedEOF, OSError:
+            pass
+        await self._transport.close()
+
+    def cipher(self) -> CipherSuite | int | None:
+        return self._buffer.cipher()
+
+    def negotiated_protocol(self) -> NextProtocol | bytes | None:
+        return self._buffer.negotiated_protocol()
+
+    @property
+    def negotiated_tls_version(self) -> TLSVersion | None:
+        return self._buffer.negotiated_tls_version
+
+    def getpeercert(self) -> bytes | None:
+        return self._buffer.getpeercert()
+
+    @classmethod
+    async def associate(
+        cls, proxy: Proxy, transport: AsyncTransport
+    ) -> tuple[str, int]:
+        _, (host, port) = await cls._converse(
+            proxy.associate(("0.0.0.0", 0)), transport
+        )
+        return (proxy.host if host in ("0.0.0.0", "::") else host, port)
+
+    @classmethod
+    async def _tunnel(
+        cls, proxy: Proxy, destination: tuple[str, int], transport: AsyncTransport
+    ) -> bytes:
+        host, port = destination
+        if (family := proxy.scheme.local_address_family) is not None:
+            candidates = await asyncio.get_running_loop().getaddrinfo(
+                host, port, family=family, type=socket.SOCK_STREAM
+            )
+            host = str(candidates[0][4][0])
+        leftover, _ = await cls._converse(proxy.converse((host, port)), transport)
+        return leftover
+
+    @staticmethod
+    async def _converse[ResultT](
+        conversation: Generator[tuple[bytes, int | bytes], bytes, ResultT],
+        transport: AsyncTransport,
+    ) -> tuple[bytes, ResultT]:
+        pending = bytearray()
+        step = next(conversation)
+        while True:
+            request, expected = step
+            if request:
+                await transport.write(request)
+            while not (end := Proxy.reply_length(pending, expected)):
+                piece = await transport.read(RECEIVE_SIZE)
+                if not piece:
+                    raise ProxyError(
+                        "the proxy closed the connection during the tunnel handshake"
+                    )
+                pending += piece
+            reply = bytes(pending[:end])
+            del pending[:end]
+            try:
+                step = conversation.send(reply)
+            except StopIteration as stop:
+                return bytes(pending), cast(ResultT, stop.value)
+
+    async def _run[ResultT](self, operation: Callable[[], ResultT]) -> ResultT:
+        while True:
+            try:
+                result = operation()
+            except WantReadError:
+                await self._flush()
+                await self._fill()
+                continue
+            except WantWriteError:
+                await self._flush()
+                continue
+            await self._flush()
+            return result
+
+    async def _flush(self) -> None:
+        # one take of everything buffered: draining a memory BIO in small pieces moves the remainder each time
+        while pending := self._buffer.outgoing_bytes_buffered():
+            await self._transport.write(self._buffer.process_outgoing(pending))
+
+    async def _fill(self) -> None:
+        data = await self._transport.read(RECEIVE_SIZE)
+        if not data:
+            raise RaggedEOF("the transport closed before close_notify")
+        self._buffer.process_incoming(data)

ssl2/client_hello.py

@@ -0,0 +1,353 @@
+from collections.abc import Iterable
+from dataclasses import dataclass, replace
+from typing import Final, Self, final
+
+from ssl2.parameters import (
+    CertificateCompressionAlgorithm,
+    CipherSuite,
+    CodePoint,
+    ContentType,
+    ECPointFormat,
+    ExtensionType,
+    HandshakeType,
+    NamedGroup,
+    NextProtocol,
+    ProtocolVersion,
+    PskKeyExchangeMode,
+    SignatureScheme,
+)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ClientHello:
+    legacy_version: ProtocolVersion = ProtocolVersion.TLS_1_2
+    supported_versions: tuple[ProtocolVersion, ...] = (ProtocolVersion.TLS_1_2,)
+    cipher_suites: tuple[CipherSuite, ...]
+    extensions: tuple[ExtensionType, ...]
+    supported_groups: tuple[NamedGroup, ...] = ()
+    key_share_groups: tuple[NamedGroup, ...] = ()
+    ec_point_formats: tuple[ECPointFormat, ...] = ()
+    signature_algorithms: tuple[SignatureScheme, ...] = ()
+    application_protocols: tuple[bytes, ...] = ()
+    application_settings: tuple[bytes, ...] = ()
+    certificate_compression_algorithms: tuple[CertificateCompressionAlgorithm, ...] = ()
+    psk_key_exchange_modes: tuple[PskKeyExchangeMode, ...] = ()
+    delegated_credential_schemes: tuple[SignatureScheme, ...] = ()
+    record_size_limit: int | None = None
+    grease: bool = False
+    permute_extensions: bool = False
+
+    def __post_init__(self) -> None:
+        if len(set(self.extensions)) != len(self.extensions):
+            raise ValueError("extensions must not repeat")
+        if len(set(self.supported_versions)) != len(self.supported_versions):
+            raise ValueError("supported_versions must not repeat")
+        payloads: tuple[tuple[object, ExtensionType], ...] = (
+            (self.supported_groups, ExtensionType.supported_groups),
+            (self.key_share_groups, ExtensionType.key_share),
+            (self.ec_point_formats, ExtensionType.ec_point_formats),
+            (self.signature_algorithms, ExtensionType.signature_algorithms),
+            (
+                self.application_protocols,
+                ExtensionType.application_layer_protocol_negotiation,
+            ),
+            (
+                self.certificate_compression_algorithms,
+                ExtensionType.compress_certificate,
+            ),
+            (self.psk_key_exchange_modes, ExtensionType.psk_key_exchange_modes),
+            (self.delegated_credential_schemes, ExtensionType.delegated_credential),
+            (self.record_size_limit, ExtensionType.record_size_limit),
+        )
+        for value, extension in payloads:
+            if bool(value) != self.offers(extension):
+                raise ValueError(
+                    f"{extension.name} needs its payload and its extension together"
+                )
+        settings = {
+            ExtensionType.application_settings,
+            ExtensionType.application_settings_old,
+        }
+        if len(settings & set(self.extensions)) != bool(self.application_settings):
+            raise ValueError(
+                "application_settings needs exactly one application_settings extension codepoint"
+            )
+        if not self._is_subsequence(self.key_share_groups, self.supported_groups):
+            raise ValueError(
+                "key_share_groups must follow the order of supported_groups"
+            )
+        if not self.offers(
+            ExtensionType.supported_versions
+        ) and self.supported_versions != (self.legacy_version,):
+            raise ValueError(
+                "without the supported_versions extension only the legacy version is offered"
+            )
+
+    def offers(self, extension: ExtensionType) -> bool:
+        return extension in self.extensions
+
+    @property
+    def highest_version(self) -> ProtocolVersion:
+        return max(self.supported_versions)
+
+    @property
+    def lowest_version(self) -> ProtocolVersion:
+        return min(self.supported_versions)
+
+    @staticmethod
+    def _is_subsequence(
+        part: tuple[NamedGroup, ...], whole: tuple[NamedGroup, ...]
+    ) -> bool:
+        position = 0
+        for group in whole:
+            if position < len(part) and part[position] == group:
+                position += 1
+        return position == len(part)
+
+
+EMPTY_CLIENT_HELLO: Final = ClientHello(cipher_suites=(), extensions=())
+
+
+class ClientHelloBuilder:
+    def __init__(self) -> None:
+        self._fields: dict[str, object] = {}
+
+    def legacy_version(self, version: ProtocolVersion | int) -> Self:
+        return self._set("legacy_version", ProtocolVersion(version))
+
+    def supported_versions(self, *versions: ProtocolVersion | int) -> Self:
+        return self._set(
+            "supported_versions",
+            tuple(ProtocolVersion(version) for version in versions),
+        )
+
+    def cipher_suites(self, *suites: CipherSuite | int) -> Self:
+        return self._set("cipher_suites", tuple(CipherSuite(suite) for suite in suites))
+
+    def extensions(self, *types: ExtensionType | int) -> Self:
+        return self._set("extensions", tuple(ExtensionType(type) for type in types))
+
+    def supported_groups(self, *groups: NamedGroup | int) -> Self:
+        return self._set(
+            "supported_groups", tuple(NamedGroup(group) for group in groups)
+        )
+
+    def key_shares(self, *groups: NamedGroup | int) -> Self:
+        return self._set(
+            "key_share_groups", tuple(NamedGroup(group) for group in groups)
+        )
+
+    def ec_point_formats(self, *formats: ECPointFormat | int) -> Self:
+        return self._set(
+            "ec_point_formats", tuple(ECPointFormat(format) for format in formats)
+        )
+
+    def signature_algorithms(self, *schemes: SignatureScheme | int) -> Self:
+        return self._set(
+            "signature_algorithms", tuple(SignatureScheme(scheme) for scheme in schemes)
+        )
+
+    def application_protocols(self, *protocols: NextProtocol | bytes) -> Self:
+        return self._set("application_protocols", self._protocol_bytes(protocols))
+
+    def application_settings(self, *protocols: NextProtocol | bytes) -> Self:
+        return self._set("application_settings", self._protocol_bytes(protocols))
+
+    def certificate_compression(
+        self, *algorithms: CertificateCompressionAlgorithm | int
+    ) -> Self:
+        algorithms_typed = tuple(
+            CertificateCompressionAlgorithm(algorithm) for algorithm in algorithms
+        )
+        return self._set("certificate_compression_algorithms", algorithms_typed)
+
+    def psk_key_exchange_modes(self, *modes: PskKeyExchangeMode | int) -> Self:
+        return self._set(
+            "psk_key_exchange_modes", tuple(PskKeyExchangeMode(mode) for mode in modes)
+        )
+
+    def delegated_credentials(self, *schemes: SignatureScheme | int) -> Self:
+        return self._set(
+            "delegated_credential_schemes",
+            tuple(SignatureScheme(scheme) for scheme in schemes),
+        )
+
+    def record_size_limit(self, limit: int | None) -> Self:
+        return self._set("record_size_limit", limit)
+
+    def grease(self, enabled: bool = True) -> Self:
+        return self._set("grease", enabled)
+
+    def permute_extensions(self, enabled: bool = True) -> Self:
+        return self._set("permute_extensions", enabled)
+
+    def build(self) -> ClientHello:
+        return replace(EMPTY_CLIENT_HELLO, **self._fields)
+
+    def _set(self, name: str, value: object) -> Self:
+        self._fields[name] = value
+        return self
+
+    @staticmethod
+    def _protocol_bytes(protocols: Iterable[NextProtocol | bytes]) -> tuple[bytes, ...]:
+        return tuple(
+            protocol.value if isinstance(protocol, NextProtocol) else protocol
+            for protocol in protocols
+        )
+
+
+@final
+class ByteReader:
+    def __init__(self, data: bytes) -> None:
+        self._data = data
+        self._position = 0
+
+    @property
+    def remaining(self) -> int:
+        return len(self._data) - self._position
+
+    def take(self, length: int) -> bytes:
+        if length > self.remaining:
+            raise ValueError("truncated ClientHello")
+        chunk = self._data[self._position : self._position + length]
+        self._position += length
+        return chunk
+
+    def integer(self, width: int) -> int:
+        return int.from_bytes(self.take(width), "big")
+
+    def vector(self, length_width: int) -> bytes:
+        return self.take(self.integer(length_width))
+
+    def integers(self, length_width: int, item_width: int) -> tuple[int, ...]:
+        body = self.vector(length_width)
+        if len(body) % item_width:
+            raise ValueError("malformed vector length")
+        return tuple(
+            int.from_bytes(body[offset : offset + item_width], "big")
+            for offset in range(0, len(body), item_width)
+        )
+
+    def strings(self, length_width: int, item_length_width: int) -> tuple[bytes, ...]:
+        inner = ByteReader(self.vector(length_width))
+        items: list[bytes] = []
+        while inner.remaining:
+            items.append(inner.vector(item_length_width))
+        return tuple(items)
+
+
+@final
+class ClientHelloParser:
+    def __init__(self) -> None:
+        self._fields: dict[str, object] = {}
+        self._grease = False
+
+    @classmethod
+    def parse(cls, data: bytes) -> ClientHello:
+        if not data:
+            raise ValueError("empty ClientHello")
+        if data[0] == ContentType.handshake:
+            data = cls._unwrap_records(data)
+        reader = ByteReader(data)
+        if reader.integer(1) != HandshakeType.client_hello:
+            raise ValueError("not a ClientHello")
+        parser = cls()
+        parser._read_body(ByteReader(reader.vector(3)))
+        return replace(EMPTY_CLIENT_HELLO, **parser._fields, grease=parser._grease)
+
+    @staticmethod
+    def _unwrap_records(data: bytes) -> bytes:
+        reader = ByteReader(data)
+        message = bytearray()
+        while reader.remaining:
+            content_type = reader.integer(1)
+            _ = reader.take(2)
+            fragment = reader.vector(2)
+            if content_type != ContentType.handshake:
+                raise ValueError("record is not a handshake record")
+            message += fragment
+            if len(message) >= 4 and len(message) >= 4 + int.from_bytes(
+                message[1:4], "big"
+            ):
+                break
+        return bytes(message)
+
+    def _read_body(self, body: ByteReader) -> None:
+        legacy_version = ProtocolVersion(body.integer(2))
+        _ = body.take(32)
+        _ = body.vector(1)
+        self._fields["legacy_version"] = legacy_version
+        self._fields["supported_versions"] = (legacy_version,)
+        self._fields["cipher_suites"] = self._typed(CipherSuite, body.integers(2, 2))
+        _ = body.vector(1)
+        extensions: list[ExtensionType] = []
+        if body.remaining:
+            block = ByteReader(body.vector(2))
+            while block.remaining:
+                extension_type = ExtensionType(block.integer(2))
+                payload = ByteReader(block.vector(2))
+                if extension_type.is_grease:
+                    self._grease = True
+                    continue
+                extensions.append(extension_type)
+                self._read_payload(extension_type, payload)
+        self._fields["extensions"] = tuple(extensions)
+
+    def _read_payload(self, extension_type: ExtensionType, payload: ByteReader) -> None:
+        match extension_type:
+            case ExtensionType.supported_versions:
+                self._fields["supported_versions"] = self._typed(
+                    ProtocolVersion, payload.integers(1, 2)
+                )
+            case ExtensionType.supported_groups:
+                self._fields["supported_groups"] = self._typed(
+                    NamedGroup, payload.integers(2, 2)
+                )
+            case ExtensionType.ec_point_formats:
+                self._fields["ec_point_formats"] = self._typed(
+                    ECPointFormat, payload.integers(1, 1)
+                )
+            case ExtensionType.signature_algorithms:
+                self._fields["signature_algorithms"] = self._typed(
+                    SignatureScheme, payload.integers(2, 2)
+                )
+            case ExtensionType.application_layer_protocol_negotiation:
+                self._fields["application_protocols"] = payload.strings(2, 1)
+            case (
+                ExtensionType.application_settings
+                | ExtensionType.application_settings_old
+            ):
+                self._fields["application_settings"] = payload.strings(2, 1)
+            case ExtensionType.key_share:
+                shares = ByteReader(payload.vector(2))
+                groups: list[int] = []
+                while shares.remaining:
+                    groups.append(shares.integer(2))
+                    _ = shares.vector(2)
+                self._fields["key_share_groups"] = self._typed(
+                    NamedGroup, tuple(groups)
+                )
+            case ExtensionType.psk_key_exchange_modes:
+                self._fields["psk_key_exchange_modes"] = self._typed(
+                    PskKeyExchangeMode, payload.integers(1, 1)
+                )
+            case ExtensionType.compress_certificate:
+                self._fields["certificate_compression_algorithms"] = self._typed(
+                    CertificateCompressionAlgorithm, payload.integers(1, 2)
+                )
+            case ExtensionType.delegated_credential:
+                self._fields["delegated_credential_schemes"] = self._typed(
+                    SignatureScheme, payload.integers(2, 2)
+                )
+            case ExtensionType.record_size_limit:
+                self._fields["record_size_limit"] = payload.integer(2)
+            case _:
+                pass
+
+    def _typed[CodePointT: CodePoint](
+        self, registry: type[CodePointT], values: tuple[int, ...]
+    ) -> tuple[CodePointT, ...]:
+        members = tuple(registry(value) for value in values)
+        kept = tuple(member for member in members if not member.is_grease)
+        self._grease |= len(kept) != len(members)
+        return kept