boring-ssl2 2.0.1__py3-none-win_amd64.whl

boring_ssl2/__init__.py

@@ -0,0 +1,27 @@
+from boring_ssl2.buffer import TLSBuffer
+from boring_ssl2.compression import BrotliDecoder
+from boring_ssl2.contexts import BoringSSL, ClientContext, ServerContext
+from boring_ssl2.errors import BoringSSLError, CertificateVerificationError
+from boring_ssl2.library import Library
+from boring_ssl2.profile import ClientHelloProfile
+from boring_ssl2.quic import EncryptionLevel, PacketProtection, QuicHandshake, QuicVersion, Suite
+from boring_ssl2.revocation import CertificateRevocationList, ParsedCertificate
+
+__all__ = (
+    "BoringSSL",
+    "BoringSSLError",
+    "BrotliDecoder",
+    "CertificateRevocationList",
+    "CertificateVerificationError",
+    "ClientContext",
+    "ClientHelloProfile",
+    "EncryptionLevel",
+    "Library",
+    "PacketProtection",
+    "ParsedCertificate",
+    "QuicHandshake",
+    "QuicVersion",
+    "ServerContext",
+    "Suite",
+    "TLSBuffer",
+)

boring_ssl2/binding.py

@@ -0,0 +1,101 @@
+import ctypes
+import sys
+from collections.abc import Callable
+from ctypes import (
+    CFUNCTYPE,
+    c_char_p,
+    c_int,
+    c_long,
+    c_size_t,
+    c_ssize_t,
+    c_uint,
+    c_uint8,
+    c_uint16,
+    c_uint32,
+    c_void_p,
+)
+from enum import IntEnum, StrEnum
+from pathlib import Path
+from typing import Any
+
+from ssl2.errors import ConfigurationError
+
+from boring_ssl2.errors import BoringSSLError
+
+type Foreign = type[c_char_p | c_int | c_long | c_size_t | c_ssize_t | c_uint | c_uint16 | c_uint32 | c_void_p]
+
+
+class FileName(StrEnum):
+    # what CMake installs next to this package on each platform
+    LINUX = "libboring_ssl2.so"
+    DARWIN = "libboring_ssl2.dylib"
+    WINDOWS = "boring_ssl2.dll"
+
+
+class Size(IntEnum):
+    ERROR_STRING = 256
+
+
+class Callback:
+    # the C function pointer types BoringSSL and brotli call back into
+    CERTIFICATE_COMPRESS = CFUNCTYPE(c_int, c_void_p, c_void_p, c_void_p, c_size_t)
+    CERTIFICATE_DECOMPRESS = CFUNCTYPE(c_int, c_void_p, c_void_p, c_size_t, c_void_p, c_size_t)
+    PROTOCOL_SELECT = CFUNCTYPE(c_int, c_void_p, c_void_p, c_void_p, c_void_p, c_uint, c_void_p)
+    SERVER_NAME = CFUNCTYPE(c_int, c_void_p, c_void_p, c_void_p)
+    NEW_SESSION = CFUNCTYPE(c_int, c_void_p, c_void_p)
+    KEY_LOG = CFUNCTYPE(None, c_void_p, c_char_p)
+    QUIC_SET_SECRET = CFUNCTYPE(c_int, c_void_p, c_int, c_void_p, c_void_p, c_size_t)
+    QUIC_ADD_HANDSHAKE_DATA = CFUNCTYPE(c_int, c_void_p, c_int, c_void_p, c_size_t)
+    QUIC_FLUSH_FLIGHT = CFUNCTYPE(c_int, c_void_p)
+    QUIC_SEND_ALERT = CFUNCTYPE(c_int, c_void_p, c_int, c_uint8)
+
+
+class LibraryPath:
+    @staticmethod
+    def bundled() -> Path:
+        directory = Path(__file__).parent
+        if sys.platform == "win32":
+            name = FileName.WINDOWS
+        elif sys.platform in ("darwin", "ios"):
+            name = FileName.DARWIN
+        else:
+            name = FileName.LINUX
+        path = directory / name
+        if not path.exists():
+            raise ConfigurationError(
+                f"no BoringSSL build at {path}; build one with cmake (see README.md) or pass Library(path=...)"
+            )
+        return path
+
+
+class Binder:
+    # loads one shared object and binds its functions the first time each is used, so a build that lacks
+    # a function fails at the call that needs it and names it
+    def __init__(self, path: Path | str | None = None) -> None:
+        self.path = Path(path) if path is not None else LibraryPath.bundled()
+        self._handle = ctypes.CDLL(str(self.path))
+
+    def bind(self, name: str, result: Foreign | None, *arguments: Foreign) -> Callable[..., Any]:
+        try:
+            function = self._handle[name]
+        except AttributeError:
+            raise ConfigurationError(
+                f"{self.path} has no {name}; this BoringSSL build predates the feature that needs it"
+            ) from None
+        function.restype = result
+        function.argtypes = arguments
+        return function
+
+    def errors(self) -> tuple[str, ...]:
+        # drains BoringSSL's error queue into readable reasons
+        get_error = self.bind("ERR_get_error", c_uint32)
+        error_string = self.bind("ERR_error_string_n", c_char_p, c_uint32, c_void_p, c_size_t)
+        text = ctypes.create_string_buffer(Size.ERROR_STRING)
+        messages: list[str] = []
+        while code := get_error():
+            error_string(code, text, len(text))
+            messages.append(ctypes.string_at(text).decode("ascii", "replace"))
+        return tuple(messages)
+
+    def error(self, operation: str) -> BoringSSLError:
+        return BoringSSLError(operation, self.errors())

boring_ssl2/buffer.py

@@ -0,0 +1,247 @@
+import ctypes
+from collections.abc import Buffer, Callable
+from enum import IntEnum
+from typing import overload
+
+from ssl2.errors import EarlyDataRejectedError, RaggedEOF, WantReadError, WantWriteError
+from ssl2.interface import ClientContext, Limit, ServerContext
+from ssl2.registry import CipherSuite, NextProtocol, ProtocolVersion, TLSVersion
+
+from boring_ssl2.errors import BoringSSLError, CertificateVerificationError
+from boring_ssl2.library import Library
+
+
+class SSLErrorCode(IntEnum):
+    # SSL_get_error
+    NONE = 0
+    SSL = 1
+    WANT_READ = 2
+    WANT_WRITE = 3
+    SYSCALL = 5
+    ZERO_RETURN = 6
+    EARLY_DATA_REJECTED = 15
+
+
+class VerifyResult(IntEnum):
+    OK = 0
+
+
+class ExDataIndex(IntEnum):
+    # slot 0 is SSL_set_app_data; the new session callback reads the cache key back from it
+    SESSION_KEY = 0
+
+
+class CInt(IntEnum):
+    # the most SSL_read and SSL_write take in one call
+    MAXIMUM = 2**31 - 1
+
+
+class TLSBuffer:
+    def __init__(
+        self,
+        context: ClientContext | ServerContext,
+        library: Library,
+        context_handle: int,
+        *,
+        server: bool,
+        session_key: str | None = None,
+    ) -> None:
+        self._context = context
+        self._library = library
+        handle = library.SSL_new(context_handle)
+        if handle is None:
+            raise library.error("SSL_new")
+        self._handle = handle
+        incoming, outgoing = library.BIO_new(library.BIO_s_mem()), library.BIO_new(library.BIO_s_mem())
+        if incoming is None or outgoing is None:
+            raise library.error("BIO_new")
+        self._incoming = incoming
+        self._outgoing = outgoing
+        library.SSL_set_bio(handle, incoming, outgoing)
+        if server:
+            library.SSL_set_accept_state(handle)
+        else:
+            library.SSL_set_connect_state(handle)
+        self._closing = False
+        self._storage = ctypes.create_string_buffer(Limit.RECEIVE)
+        self._session_key = None if session_key is None else ctypes.create_string_buffer(session_key.encode())
+        if self._session_key is not None:
+            library.check(
+                library.SSL_set_ex_data(handle, ExDataIndex.SESSION_KEY, ctypes.addressof(self._session_key)),
+                "SSL_set_ex_data",
+            )
+
+    def __del__(self) -> None:
+        self._library.SSL_free(self._handle)
+
+    @property
+    def handle(self) -> int:
+        return self._handle
+
+    @property
+    def library(self) -> Library:
+        return self._library
+
+    @property
+    def context(self) -> ClientContext | ServerContext:
+        return self._context
+
+    @property
+    def session_reused(self) -> bool:
+        return self._library.SSL_session_reused(self._handle) == 1
+
+    @overload
+    def read(self, amount: int) -> bytes: ...
+
+    @overload
+    def read(self, amount: int, buffer: Buffer) -> int: ...
+
+    def read(self, amount: int, buffer: Buffer | None = None) -> bytes | int:
+        if buffer is None:
+            size = min(amount, CInt.MAXIMUM)
+            storage = (
+                (ctypes.c_char * size).from_buffer(self._storage)
+                if size <= Limit.RECEIVE
+                else ctypes.create_string_buffer(size)
+            )
+            count = self._read_into(storage)
+            return ctypes.string_at(storage, count)
+        view = memoryview(buffer).cast("B")
+        return self._read_into((ctypes.c_char * min(amount, view.nbytes, CInt.MAXIMUM)).from_buffer(view))
+
+    def write(self, data: Buffer) -> int:
+        payload = bytes(data)
+        if not payload:
+            # BoringSSL holds post-handshake tickets until the first write; a zero-length write releases them
+            self._library.SSL_write(self._handle, payload, 0)
+            return 0
+        size = min(len(payload), CInt.MAXIMUM)
+        return self._operate(lambda: self._library.SSL_write(self._handle, payload, size), "write")
+
+    def attach(self, fileno: int) -> None:
+        # the socket becomes BoringSSL's own BIO: records move between the kernel and the TLS state with no stop here
+        self._library.check(self._library.SSL_set_fd(self._handle, fileno), "SSL_set_fd")
+
+    def do_handshake(self) -> None:
+        self._operate(lambda: self._library.SSL_do_handshake(self._handle), "handshake")
+
+    def cipher(self) -> CipherSuite | int | None:
+        cipher = self._library.SSL_get_current_cipher(self._handle)
+        return None if cipher is None else CipherSuite(self._library.SSL_CIPHER_get_protocol_id(cipher))
+
+    def negotiated_protocol(self) -> NextProtocol | bytes | None:
+        data, length = ctypes.c_void_p(), ctypes.c_uint()
+        self._library.SSL_get0_alpn_selected(self._handle, ctypes.byref(data), ctypes.byref(length))
+        if data.value is None or not length.value:
+            return None
+        selected = ctypes.string_at(data.value, length.value)
+        try:
+            return NextProtocol(selected)
+        except ValueError:
+            return selected
+
+    @property
+    def negotiated_tls_version(self) -> TLSVersion | None:
+        if not self._library.SSL_is_init_finished(self._handle):
+            return None
+        return ProtocolVersion(self._library.SSL_version(self._handle)).tls_version
+
+    def shutdown(self) -> None:
+        if not self._closing:
+            self._library.ERR_clear_error()
+            result = self._library.SSL_shutdown(self._handle)
+            if result < 0:
+                failure = self._failure(result, "shutdown")
+                if failure is not None:
+                    raise failure
+            self._closing = True
+            if result == 1:
+                return
+        # BoringSSL refuses application data that arrives before the peer's close_notify, so it is read away
+        storage = ctypes.create_string_buffer(Limit.RECEIVE)
+        while self._read_into(storage):
+            pass
+
+    def process_incoming(self, data_from_network: bytes) -> None:
+        written = self._library.BIO_write(self._incoming, data_from_network, len(data_from_network))
+        if written != len(data_from_network):
+            raise self._library.error("BIO_write")
+
+    def incoming_bytes_buffered(self) -> int:
+        return self._library.BIO_ctrl_pending(self._incoming)
+
+    def process_outgoing(self, amount_bytes_for_network: int) -> bytes:
+        storage = ctypes.create_string_buffer(min(amount_bytes_for_network, CInt.MAXIMUM))
+        count = self._library.BIO_read(self._outgoing, storage, len(storage))
+        return ctypes.string_at(storage, count) if count > 0 else b""
+
+    def outgoing_bytes_buffered(self) -> int:
+        return self._library.BIO_ctrl_pending(self._outgoing)
+
+    def getpeercert(self) -> bytes | None:
+        chain = self.getpeerchain()
+        return chain[0] if chain else None
+
+    def getpeerchain(self) -> tuple[bytes, ...]:
+        library = self._library
+        stack = library.SSL_get0_peer_certificates(self._handle)
+        if stack is None:
+            return ()
+        certificates: list[bytes] = []
+        for index in range(library.OPENSSL_sk_num(stack)):
+            item = library.OPENSSL_sk_value(stack, index)
+            certificates.append(ctypes.string_at(library.CRYPTO_BUFFER_data(item), library.CRYPTO_BUFFER_len(item)))
+        return tuple(certificates)
+
+    def _read_into(self, storage: ctypes.Array[ctypes.c_char]) -> int:
+        size = len(storage)
+        if not size:
+            return 0
+        handle, library = self._handle, self._library
+        total = self._operate(lambda: library.SSL_read(handle, storage, size), "read")
+        # one SSL_read returns one record; the records already in the memory BIO or the kernel follow in this call.
+        # An attached socket is non-blocking, so BoringSSL answers WANT_READ when they run out, never a block
+        while 0 < total < size:
+            rest = (ctypes.c_char * (size - total)).from_buffer(storage, total)
+            more = library.SSL_read(handle, rest, size - total)
+            if more <= 0:
+                break
+            total += more
+        return total
+
+    def _operate(self, call: Callable[[], int], operation: str) -> int:
+        self._library.ERR_clear_error()
+        result = call()
+        if result > 0:
+            return result
+        failure = self._failure(result, operation)
+        if failure is None:
+            return 0
+        raise failure
+
+    def _failure(self, result: int, operation: str) -> Exception | None:
+        library = self._library
+        code = library.SSL_get_error(self._handle, result)
+        reasons = library.errors()
+        match code:
+            case SSLErrorCode.WANT_READ:
+                return WantReadError(f"{operation} needs more data from the peer")
+            case SSLErrorCode.WANT_WRITE:
+                return WantWriteError(f"{operation} needs the outgoing buffer drained")
+            case SSLErrorCode.ZERO_RETURN:
+                return None
+            case SSLErrorCode.EARLY_DATA_REJECTED:
+                return EarlyDataRejectedError(f"{operation}: the server declined the early data")
+            case SSLErrorCode.SSL:
+                verdict = library.SSL_get_verify_result(self._handle)
+                if verdict != VerifyResult.OK:
+                    return CertificateVerificationError(
+                        operation, reasons, library.X509_verify_cert_error_string(verdict).decode("ascii")
+                    )
+                return BoringSSLError(operation, reasons)
+            case SSLErrorCode.SYSCALL:
+                # end of stream, a reset or a timeout on the socket: the connection is gone either way
+                detail = f": {'; '.join(reasons)}" if reasons else ""
+                return RaggedEOF(f"{operation}: the connection ended without close_notify{detail}")
+            case _:
+                return BoringSSLError(operation, (f"SSL_get_error={code}", *reasons))

boring_ssl2/compression.py

@@ -0,0 +1,148 @@
+import ctypes
+import zlib
+from compression import zstd
+from enum import IntEnum
+
+from ssl2.errors import ConfigurationError
+from ssl2.registry import CertificateCompressionAlgorithm
+
+from boring_ssl2.binding import Callback
+from boring_ssl2.library import Library
+
+
+class BrotliEncoderSetting(IntEnum):
+    # the quality, window and mode brotli's one-shot encoder takes
+    QUALITY = 11
+    WINDOW = 22
+    MODE_GENERIC = 0
+
+
+class BrotliResult(IntEnum):
+    # what the one-shot calls and the stream decoder answer
+    FALSE = 0
+    TRUE = 1
+    NEEDS_MORE_INPUT = 2
+    NEEDS_MORE_OUTPUT = 3
+
+
+class Size(IntEnum):
+    OUTPUT_CHUNK = 65536
+
+
+class BrotliDecoder:
+    # a streaming decoder for brotli bodies, fed in pieces as they arrive
+    def __init__(self, library: Library | None = None) -> None:
+        self._library = library or Library.default()
+        state = self._library.BrotliDecoderCreateInstance(None, None, None)
+        if state is None:
+            raise MemoryError("brotli decoder state")
+        self._state = state
+        self.finished = False
+
+    def __del__(self) -> None:
+        self._library.BrotliDecoderDestroyInstance(self._state)
+
+    def decode(self, data: bytes) -> bytes:
+        storage = ctypes.create_string_buffer(data, len(data))
+        available_in = ctypes.c_size_t(len(data))
+        next_in = ctypes.c_void_p(ctypes.addressof(storage))
+        chunks: list[bytes] = []
+        while True:
+            output = ctypes.create_string_buffer(Size.OUTPUT_CHUNK)
+            available_out = ctypes.c_size_t(Size.OUTPUT_CHUNK)
+            next_out = ctypes.c_void_p(ctypes.addressof(output))
+            result = self._library.BrotliDecoderDecompressStream(
+                self._state,
+                ctypes.byref(available_in),
+                ctypes.byref(next_in),
+                ctypes.byref(available_out),
+                ctypes.byref(next_out),
+                None,
+            )
+            chunks.append(output.raw[: Size.OUTPUT_CHUNK - available_out.value])
+            match result:
+                case BrotliResult.NEEDS_MORE_OUTPUT:
+                    continue
+                case BrotliResult.NEEDS_MORE_INPUT:
+                    return b"".join(chunks)
+                case BrotliResult.TRUE:
+                    self.finished = True
+                    return b"".join(chunks)
+                case _:
+                    raise ValueError("corrupt brotli stream")
+
+
+class CertificateCompression:
+    # RFC 8879: the client decompresses the server's certificate, the server compresses its own
+    def __init__(self, library: Library) -> None:
+        self._library = library
+        self._callbacks: list[object] = []
+
+    def register(self, handle: int, algorithm: CertificateCompressionAlgorithm, *, client: bool) -> None:
+        if not algorithm.is_assigned:
+            raise ConfigurationError(f"no certificate compression codec for {algorithm.name}")
+        library = self._library
+
+        def compress(_ssl: int, out: int, data: int, length: int) -> int:
+            try:
+                encoded = self._encode(algorithm, ctypes.string_at(data, length))
+            except ValueError, zlib.error, zstd.ZstdError:
+                return BrotliResult.FALSE
+            return library.CBB_add_bytes(out, encoded, len(encoded))
+
+        def decompress(_ssl: int, out: int, size: int, data: int, length: int) -> int:
+            try:
+                decoded = self._decode(algorithm, ctypes.string_at(data, length), size)
+            except ValueError, zlib.error, zstd.ZstdError:
+                return BrotliResult.FALSE
+            buffer = library.CRYPTO_BUFFER_new(decoded, len(decoded), None)
+            if len(decoded) != size or buffer is None:
+                return BrotliResult.FALSE
+            ctypes.c_void_p.from_address(out).value = buffer
+            return BrotliResult.TRUE
+
+        compressor = None if client else Callback.CERTIFICATE_COMPRESS(compress)
+        decompressor = Callback.CERTIFICATE_DECOMPRESS(decompress) if client else None
+        self._callbacks += (compressor, decompressor)
+        library.check(
+            library.SSL_CTX_add_cert_compression_alg(handle, algorithm, compressor, decompressor),
+            "SSL_CTX_add_cert_compression_alg",
+        )
+
+    def _encode(self, algorithm: CertificateCompressionAlgorithm, data: bytes) -> bytes:
+        match algorithm:
+            case CertificateCompressionAlgorithm.zlib:
+                return zlib.compress(data)
+            case CertificateCompressionAlgorithm.zstd:
+                return zstd.compress(data)
+            case CertificateCompressionAlgorithm.brotli:
+                library = self._library
+                capacity = library.BrotliEncoderMaxCompressedSize(len(data))
+                storage = ctypes.create_string_buffer(capacity)
+                size = ctypes.c_size_t(capacity)
+                accepted = library.BrotliEncoderCompress(
+                    BrotliEncoderSetting.QUALITY,
+                    BrotliEncoderSetting.WINDOW,
+                    BrotliEncoderSetting.MODE_GENERIC,
+                    len(data),
+                    data,
+                    ctypes.byref(size),
+                    storage,
+                )
+                if accepted != BrotliResult.TRUE:
+                    raise ValueError("brotli compression failed")
+                return storage.raw[: size.value]
+
+    def _decode(self, algorithm: CertificateCompressionAlgorithm, data: bytes, size: int) -> bytes:
+        match algorithm:
+            case CertificateCompressionAlgorithm.zlib:
+                return zlib.decompress(data, bufsize=size)
+            case CertificateCompressionAlgorithm.zstd:
+                return zstd.decompress(data)
+            case CertificateCompressionAlgorithm.brotli:
+                storage = ctypes.create_string_buffer(size)
+                decoded = ctypes.c_size_t(size)
+                accepted = self._library.BrotliDecoderDecompress(len(data), data, ctypes.byref(decoded), storage)
+                if accepted != BrotliResult.TRUE:
+                    raise ValueError("brotli decompression failed")
+                return storage.raw[: decoded.value]