tigrcorn-security 0.3.16.dev5__py3-none-any.whl

tigrcorn_security/tls13/key_schedule.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+from dataclasses import dataclass
+
+from tigrcorn_security.tls13.transcript import HandshakeTranscript
+from tigrcorn_transports.quic.crypto import hkdf_expand_label, hkdf_extract
+
+
+@dataclass(slots=True)
+class TrafficSecrets:
+    client_handshake_traffic_secret: bytes
+    server_handshake_traffic_secret: bytes
+    client_application_traffic_secret: bytes
+    server_application_traffic_secret: bytes
+    client_early_traffic_secret: bytes | None = None
+    exporter_master_secret: bytes | None = None
+    resumption_master_secret: bytes | None = None
+
+
+class Tls13KeySchedule:
+    def __init__(self, *, hash_name: str = 'sha256') -> None:
+        self.hash_name = hash_name
+        self.hash_length = hashlib.new(hash_name).digest_size
+
+    def hash_empty(self) -> bytes:
+        return hashlib.new(self.hash_name).digest()
+
+    def transcript_hash(self, transcript: HandshakeTranscript | bytes) -> bytes:
+        if isinstance(transcript, HandshakeTranscript):
+            return transcript.digest()
+        return hashlib.new(self.hash_name, transcript).digest()
+
+    def extract(self, salt: bytes, ikm: bytes) -> bytes:
+        return hkdf_extract(salt, ikm, hash_name=self.hash_name)
+
+    def expand_label(self, secret: bytes, label: bytes | str, context: bytes = b'', length: int | None = None) -> bytes:
+        return hkdf_expand_label(
+            secret,
+            label,
+            context,
+            self.hash_length if length is None else length,
+            hash_name=self.hash_name,
+        )
+
+    def derive_secret(self, secret: bytes, label: bytes | str, transcript: HandshakeTranscript | bytes | None = None) -> bytes:
+        if transcript is None:
+            context = self.hash_empty()
+        else:
+            context = self.transcript_hash(transcript)
+        return self.expand_label(secret, label, context, self.hash_length)
+
+    def zero_secret(self) -> bytes:
+        return b'\x00' * self.hash_length
+
+    def make_early_secret(self, psk: bytes | None) -> bytes:
+        ikm = self.zero_secret() if psk is None else psk
+        return self.extract(self.zero_secret(), ikm)
+
+    def make_binder_key(self, early_secret: bytes, *, external: bool = False) -> bytes:
+        label = 'ext binder' if external else 'res binder'
+        return self.derive_secret(early_secret, label)
+
+    def client_early_traffic_secret(self, early_secret: bytes, transcript: HandshakeTranscript | bytes) -> bytes:
+        return self.derive_secret(early_secret, 'c e traffic', transcript)
+
+    def handshake_secret(self, early_secret: bytes, shared_secret: bytes) -> bytes:
+        derived = self.derive_secret(early_secret, 'derived')
+        return self.extract(derived, shared_secret)
+
+    def handshake_traffic_secrets(self, handshake_secret: bytes, transcript: HandshakeTranscript | bytes) -> tuple[bytes, bytes]:
+        return (
+            self.derive_secret(handshake_secret, 'c hs traffic', transcript),
+            self.derive_secret(handshake_secret, 's hs traffic', transcript),
+        )
+
+    def finished_key(self, base_key: bytes) -> bytes:
+        return self.expand_label(base_key, 'finished', b'', self.hash_length)
+
+    def finished_verify_data(self, base_key: bytes, transcript: HandshakeTranscript | bytes) -> bytes:
+        return hmac.new(self.finished_key(base_key), self.transcript_hash(transcript), getattr(hashlib, self.hash_name)).digest()
+
+    def verify_finished(self, verify_data: bytes, *, base_key: bytes, transcript: HandshakeTranscript | bytes) -> bool:
+        expected = self.finished_verify_data(base_key, transcript)
+        return hmac.compare_digest(expected, verify_data)
+
+    def master_secret(self, handshake_secret: bytes) -> bytes:
+        derived = self.derive_secret(handshake_secret, 'derived')
+        return self.extract(derived, self.zero_secret())
+
+    def application_traffic_secrets(self, master_secret: bytes, transcript: HandshakeTranscript | bytes) -> tuple[bytes, bytes]:
+        return (
+            self.derive_secret(master_secret, 'c ap traffic', transcript),
+            self.derive_secret(master_secret, 's ap traffic', transcript),
+        )
+
+    def exporter_master_secret(self, master_secret: bytes, transcript: HandshakeTranscript | bytes) -> bytes:
+        return self.derive_secret(master_secret, 'exp master', transcript)
+
+    def resumption_master_secret(self, master_secret: bytes, transcript: HandshakeTranscript | bytes) -> bytes:
+        return self.derive_secret(master_secret, 'res master', transcript)
+
+    def resumption_psk(self, resumption_master_secret: bytes, ticket_nonce: bytes) -> bytes:
+        return self.expand_label(resumption_master_secret, 'resumption', ticket_nonce, self.hash_length)
+
+    def update_application_traffic_secret(self, traffic_secret: bytes) -> bytes:
+        return self.expand_label(traffic_secret, 'traffic upd', b'', self.hash_length)

tigrcorn_security/tls13/messages.py

@@ -0,0 +1,428 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import ClassVar, Sequence
+
+from tigrcorn_core.errors import ProtocolError
+from tigrcorn_security.tls13.extensions import (
+    ExtensionType,
+    TlsExtension,
+    TLS_LEGACY_VERSION,
+    encode_extensions,
+    decode_extensions,
+)
+
+HELLO_RETRY_REQUEST_RANDOM = bytes.fromhex(
+    'CF21AD74E59A6111BE1D8C021E65B891'
+    'C2A211167ABB8C5E079E09E2C8A8339C'
+)
+
+
+class HandshakeType(IntEnum):
+    CLIENT_HELLO = 1
+    SERVER_HELLO = 2
+    NEW_SESSION_TICKET = 4
+    END_OF_EARLY_DATA = 5
+    ENCRYPTED_EXTENSIONS = 8
+    CERTIFICATE = 11
+    CERTIFICATE_REQUEST = 13
+    CERTIFICATE_VERIFY = 15
+    FINISHED = 20
+    KEY_UPDATE = 24
+    MESSAGE_HASH = 254
+
+
+class NeedMoreData(ProtocolError):
+    pass
+
+
+
+def _u8_vector(payload: bytes) -> bytes:
+    if len(payload) > 255:
+        raise ValueError('u8 vector too large')
+    return bytes([len(payload)]) + payload
+
+
+
+def _u16_vector(payload: bytes) -> bytes:
+    if len(payload) > 0xFFFF:
+        raise ValueError('u16 vector too large')
+    return len(payload).to_bytes(2, 'big') + payload
+
+
+
+def _u24_vector(payload: bytes) -> bytes:
+    if len(payload) > 0xFFFFFF:
+        raise ValueError('u24 vector too large')
+    return len(payload).to_bytes(3, 'big') + payload
+
+
+
+def _read_exact(data: bytes, offset: int, length: int) -> tuple[bytes, int]:
+    end = offset + length
+    if end > len(data):
+        raise NeedMoreData('incomplete TLS handshake payload')
+    return data[offset:end], end
+
+
+
+def _read_u8(data: bytes, offset: int) -> tuple[int, int]:
+    raw, offset = _read_exact(data, offset, 1)
+    return raw[0], offset
+
+
+
+def _read_u16(data: bytes, offset: int) -> tuple[int, int]:
+    raw, offset = _read_exact(data, offset, 2)
+    return int.from_bytes(raw, 'big'), offset
+
+
+
+def _read_u24(data: bytes, offset: int) -> tuple[int, int]:
+    raw, offset = _read_exact(data, offset, 3)
+    return int.from_bytes(raw, 'big'), offset
+
+
+
+def _read_u32(data: bytes, offset: int) -> tuple[int, int]:
+    raw, offset = _read_exact(data, offset, 4)
+    return int.from_bytes(raw, 'big'), offset
+
+
+
+def _read_u8_vector(data: bytes, offset: int) -> tuple[bytes, int]:
+    length, offset = _read_u8(data, offset)
+    return _read_exact(data, offset, length)
+
+
+
+def _read_u16_vector(data: bytes, offset: int) -> tuple[bytes, int]:
+    length, offset = _read_u16(data, offset)
+    return _read_exact(data, offset, length)
+
+
+
+def _read_u24_vector(data: bytes, offset: int) -> tuple[bytes, int]:
+    length, offset = _read_u24(data, offset)
+    return _read_exact(data, offset, length)
+
+
+@dataclass(slots=True)
+class HandshakeMessage:
+    handshake_type: ClassVar[int]
+
+    def encode_body(self, **kwargs) -> bytes:
+        raise NotImplementedError
+
+    def encode(self, **kwargs) -> bytes:
+        body = self.encode_body(**kwargs)
+        return bytes([self.handshake_type]) + len(body).to_bytes(3, 'big') + body
+
+
+@dataclass(slots=True)
+class ClientHello(HandshakeMessage):
+    handshake_type: ClassVar[int] = HandshakeType.CLIENT_HELLO
+    random: bytes = field(default_factory=lambda: os.urandom(32))
+    legacy_session_id: bytes = field(default_factory=lambda: os.urandom(32))
+    cipher_suites: tuple[int, ...] = ()
+    compression_methods: bytes = b'\x00'
+    extensions: tuple[TlsExtension, ...] = ()
+    legacy_version: int = TLS_LEGACY_VERSION
+
+    def encode_body(self, *, message_context: str = 'client_hello', **kwargs) -> bytes:
+        if len(self.random) != 32:
+            raise ValueError('ClientHello.random must be 32 bytes')
+        if len(self.legacy_session_id) > 32:
+            raise ValueError('legacy_session_id must be <= 32 bytes')
+        cipher_payload = b''.join(cipher_suite.to_bytes(2, 'big') for cipher_suite in self.cipher_suites)
+        if len(cipher_payload) < 2:
+            raise ValueError('at least one cipher suite is required')
+        return (
+            self.legacy_version.to_bytes(2, 'big')
+            + self.random
+            + _u8_vector(self.legacy_session_id)
+            + _u16_vector(cipher_payload)
+            + _u8_vector(self.compression_methods)
+            + encode_extensions(self.extensions, message_context=message_context)
+        )
+
+    @classmethod
+    def decode_body(cls, body: bytes) -> 'ClientHello':
+        legacy_version, offset = _read_u16(body, 0)
+        random, offset = _read_exact(body, offset, 32)
+        legacy_session_id, offset = _read_u8_vector(body, offset)
+        cipher_suites_raw, offset = _read_u16_vector(body, offset)
+        compression_methods, offset = _read_u8_vector(body, offset)
+        extensions = decode_extensions(body[offset:], message_context='client_hello')
+        if len(cipher_suites_raw) % 2:
+            raise ProtocolError('invalid cipher_suites vector in ClientHello')
+        cipher_suites = tuple(int.from_bytes(cipher_suites_raw[index:index + 2], 'big') for index in range(0, len(cipher_suites_raw), 2))
+        return cls(
+            random=random,
+            legacy_session_id=legacy_session_id,
+            cipher_suites=cipher_suites,
+            compression_methods=compression_methods,
+            extensions=extensions,
+            legacy_version=legacy_version,
+        )
+
+    def with_extensions(self, extensions: Sequence[TlsExtension]) -> 'ClientHello':
+        return ClientHello(
+            random=self.random,
+            legacy_session_id=self.legacy_session_id,
+            cipher_suites=self.cipher_suites,
+            compression_methods=self.compression_methods,
+            extensions=tuple(extensions),
+            legacy_version=self.legacy_version,
+        )
+
+
+@dataclass(slots=True)
+class ServerHello(HandshakeMessage):
+    handshake_type: ClassVar[int] = HandshakeType.SERVER_HELLO
+    random: bytes
+    legacy_session_id_echo: bytes
+    cipher_suite: int
+    extensions: tuple[TlsExtension, ...]
+    legacy_version: int = TLS_LEGACY_VERSION
+    legacy_compression_method: int = 0
+
+    def encode_body(self, *, message_context: str = 'server_hello', **kwargs) -> bytes:
+        if len(self.random) != 32:
+            raise ValueError('ServerHello.random must be 32 bytes')
+        return (
+            self.legacy_version.to_bytes(2, 'big')
+            + self.random
+            + _u8_vector(self.legacy_session_id_echo)
+            + self.cipher_suite.to_bytes(2, 'big')
+            + bytes([self.legacy_compression_method])
+            + encode_extensions(self.extensions, message_context=message_context)
+        )
+
+    @property
+    def is_hello_retry_request(self) -> bool:
+        return self.random == HELLO_RETRY_REQUEST_RANDOM
+
+    @classmethod
+    def decode_body(cls, body: bytes) -> 'ServerHello':
+        legacy_version, offset = _read_u16(body, 0)
+        random, offset = _read_exact(body, offset, 32)
+        legacy_session_id_echo, offset = _read_u8_vector(body, offset)
+        cipher_suite, offset = _read_u16(body, offset)
+        legacy_compression_method, offset = _read_u8(body, offset)
+        context = 'hello_retry_request' if random == HELLO_RETRY_REQUEST_RANDOM else 'server_hello'
+        extensions = decode_extensions(body[offset:], message_context=context)
+        return cls(
+            random=random,
+            legacy_session_id_echo=legacy_session_id_echo,
+            cipher_suite=cipher_suite,
+            extensions=extensions,
+            legacy_version=legacy_version,
+            legacy_compression_method=legacy_compression_method,
+        )
+
+
+@dataclass(slots=True)
+class EncryptedExtensions(HandshakeMessage):
+    handshake_type: ClassVar[int] = HandshakeType.ENCRYPTED_EXTENSIONS
+    extensions: tuple[TlsExtension, ...]
+
+    def encode_body(self, *, message_context: str = 'encrypted_extensions', **kwargs) -> bytes:
+        return encode_extensions(self.extensions, message_context=message_context)
+
+    @classmethod
+    def decode_body(cls, body: bytes) -> 'EncryptedExtensions':
+        return cls(extensions=decode_extensions(body, message_context='encrypted_extensions'))
+
+
+@dataclass(slots=True)
+class CertificateRequest(HandshakeMessage):
+    handshake_type: ClassVar[int] = HandshakeType.CERTIFICATE_REQUEST
+    request_context: bytes = b''
+    extensions: tuple[TlsExtension, ...] = ()
+
+    def encode_body(self, *, message_context: str = 'certificate_request', **kwargs) -> bytes:
+        return _u8_vector(self.request_context) + encode_extensions(self.extensions, message_context=message_context)
+
+    @classmethod
+    def decode_body(cls, body: bytes) -> 'CertificateRequest':
+        request_context, offset = _read_u8_vector(body, 0)
+        return cls(request_context=request_context, extensions=decode_extensions(body[offset:], message_context='certificate_request'))
+
+
+@dataclass(slots=True)
+class CertificateEntry:
+    cert_data: bytes
+    extensions: tuple[TlsExtension, ...] = ()
+
+    def encode(self) -> bytes:
+        return _u24_vector(self.cert_data) + encode_extensions(self.extensions, message_context='certificate_entry')
+
+    @classmethod
+    def decode(cls, data: bytes, offset: int) -> tuple['CertificateEntry', int]:
+        cert_data, offset = _read_u24_vector(data, offset)
+        extensions_raw, offset = _read_u16_vector(data, offset)
+        extensions = decode_extensions(len(extensions_raw).to_bytes(2, 'big') + extensions_raw, message_context='certificate_entry')
+        return cls(cert_data=cert_data, extensions=extensions), offset
+
+
+@dataclass(slots=True)
+class Certificate(HandshakeMessage):
+    handshake_type: ClassVar[int] = HandshakeType.CERTIFICATE
+    request_context: bytes = b''
+    certificate_list: tuple[CertificateEntry, ...] = ()
+
+    def encode_body(self, **kwargs) -> bytes:
+        payload = bytearray()
+        for entry in self.certificate_list:
+            payload.extend(entry.encode())
+        return _u8_vector(self.request_context) + _u24_vector(bytes(payload))
+
+    @classmethod
+    def decode_body(cls, body: bytes) -> 'Certificate':
+        request_context, offset = _read_u8_vector(body, 0)
+        certificate_list_raw, offset = _read_u24_vector(body, offset)
+        if offset != len(body):
+            raise ProtocolError('invalid Certificate message length')
+        inner = 0
+        entries: list[CertificateEntry] = []
+        while inner < len(certificate_list_raw):
+            entry, inner = CertificateEntry.decode(certificate_list_raw, inner)
+            entries.append(entry)
+        return cls(request_context=request_context, certificate_list=tuple(entries))
+
+
+@dataclass(slots=True)
+class CertificateVerify(HandshakeMessage):
+    handshake_type: ClassVar[int] = HandshakeType.CERTIFICATE_VERIFY
+    algorithm: int
+    signature: bytes
+
+    def encode_body(self, **kwargs) -> bytes:
+        return self.algorithm.to_bytes(2, 'big') + _u16_vector(self.signature)
+
+    @classmethod
+    def decode_body(cls, body: bytes) -> 'CertificateVerify':
+        algorithm, offset = _read_u16(body, 0)
+        signature, offset = _read_u16_vector(body, offset)
+        if offset != len(body):
+            raise ProtocolError('invalid CertificateVerify message')
+        return cls(algorithm=algorithm, signature=signature)
+
+
+@dataclass(slots=True)
+class Finished(HandshakeMessage):
+    handshake_type: ClassVar[int] = HandshakeType.FINISHED
+    verify_data: bytes
+
+    def encode_body(self, **kwargs) -> bytes:
+        return self.verify_data
+
+    @classmethod
+    def decode_body(cls, body: bytes) -> 'Finished':
+        return cls(verify_data=body)
+
+
+@dataclass(slots=True)
+class NewSessionTicket(HandshakeMessage):
+    handshake_type: ClassVar[int] = HandshakeType.NEW_SESSION_TICKET
+    ticket_lifetime: int
+    ticket_age_add: int
+    ticket_nonce: bytes
+    ticket: bytes
+    extensions: tuple[TlsExtension, ...] = ()
+
+    def encode_body(self, **kwargs) -> bytes:
+        return (
+            self.ticket_lifetime.to_bytes(4, 'big')
+            + self.ticket_age_add.to_bytes(4, 'big')
+            + _u8_vector(self.ticket_nonce)
+            + _u16_vector(self.ticket)
+            + encode_extensions(self.extensions, message_context='new_session_ticket')
+        )
+
+    @classmethod
+    def decode_body(cls, body: bytes) -> 'NewSessionTicket':
+        ticket_lifetime, offset = _read_u32(body, 0)
+        ticket_age_add, offset = _read_u32(body, offset)
+        ticket_nonce, offset = _read_u8_vector(body, offset)
+        ticket, offset = _read_u16_vector(body, offset)
+        extensions = decode_extensions(body[offset:], message_context='new_session_ticket')
+        return cls(
+            ticket_lifetime=ticket_lifetime,
+            ticket_age_add=ticket_age_add,
+            ticket_nonce=ticket_nonce,
+            ticket=ticket,
+            extensions=extensions,
+        )
+
+
+@dataclass(slots=True)
+class KeyUpdate(HandshakeMessage):
+    handshake_type: ClassVar[int] = HandshakeType.KEY_UPDATE
+    request_update: int
+
+    def encode_body(self, **kwargs) -> bytes:
+        return bytes([self.request_update])
+
+    @classmethod
+    def decode_body(cls, body: bytes) -> 'KeyUpdate':
+        if len(body) != 1:
+            raise ProtocolError('invalid KeyUpdate message')
+        return cls(request_update=body[0])
+
+
+@dataclass(slots=True)
+class SyntheticMessageHash(HandshakeMessage):
+    handshake_type: ClassVar[int] = HandshakeType.MESSAGE_HASH
+    digest: bytes
+
+    def encode_body(self, **kwargs) -> bytes:
+        return self.digest
+
+
+@dataclass(slots=True)
+class UnknownHandshake(HandshakeMessage):
+    handshake_type: int
+    body: bytes
+
+    def encode_body(self, **kwargs) -> bytes:
+        return self.body
+
+
+_HANDSHAKE_DECODERS: dict[int, type[HandshakeMessage]] = {
+    HandshakeType.CLIENT_HELLO: ClientHello,
+    HandshakeType.SERVER_HELLO: ServerHello,
+    HandshakeType.NEW_SESSION_TICKET: NewSessionTicket,
+    HandshakeType.ENCRYPTED_EXTENSIONS: EncryptedExtensions,
+    HandshakeType.CERTIFICATE_REQUEST: CertificateRequest,
+    HandshakeType.CERTIFICATE: Certificate,
+    HandshakeType.CERTIFICATE_VERIFY: CertificateVerify,
+    HandshakeType.FINISHED: Finished,
+    HandshakeType.KEY_UPDATE: KeyUpdate,
+}
+
+
+
+def decode_handshake_message(data: bytes, offset: int = 0) -> tuple[HandshakeMessage, int]:
+    handshake_type_raw, next_offset = _read_u8(data, offset)
+    body_length, next_offset = _read_u24(data, next_offset)
+    body, next_offset = _read_exact(data, next_offset, body_length)
+    decoder = _HANDSHAKE_DECODERS.get(handshake_type_raw)
+    if decoder is None:
+        message: HandshakeMessage = UnknownHandshake(handshake_type=handshake_type_raw, body=body)
+    else:
+        message = decoder.decode_body(body)  # type: ignore[attr-defined]
+    return message, next_offset
+
+
+
+def decode_handshake_messages(data: bytes) -> tuple[HandshakeMessage, ...]:
+    messages: list[HandshakeMessage] = []
+    offset = 0
+    while offset < len(data):
+        message, offset = decode_handshake_message(data, offset)
+        messages.append(message)
+    return tuple(messages)

tigrcorn_security/tls13/transcript.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+
+from tigrcorn_security.tls13.messages import SyntheticMessageHash
+
+
+@dataclass(slots=True)
+class HandshakeTranscript:
+    hash_name: str = 'sha256'
+    _messages: bytearray = field(default_factory=bytearray)
+
+    @property
+    def hash_length(self) -> int:
+        return hashlib.new(self.hash_name).digest_size
+
+    def copy(self) -> 'HandshakeTranscript':
+        transcript = HandshakeTranscript(hash_name=self.hash_name)
+        transcript._messages.extend(self._messages)
+        return transcript
+
+    def clear(self) -> None:
+        self._messages.clear()
+
+    def append(self, encoded_handshake_message: bytes) -> None:
+        self._messages.extend(encoded_handshake_message)
+
+    def extend(self, encoded_handshake_messages: bytes) -> None:
+        self._messages.extend(encoded_handshake_messages)
+
+    def digest(self) -> bytes:
+        hasher = hashlib.new(self.hash_name)
+        hasher.update(self._messages)
+        return hasher.digest()
+
+    def digest_with(self, *encoded_handshake_messages: bytes) -> bytes:
+        hasher = hashlib.new(self.hash_name)
+        hasher.update(self._messages)
+        for message in encoded_handshake_messages:
+            hasher.update(message)
+        return hasher.digest()
+
+    def as_bytes(self) -> bytes:
+        return bytes(self._messages)
+
+    def reset_with_message_hash(self, encoded_client_hello: bytes) -> None:
+        digest = hashlib.new(self.hash_name, encoded_client_hello).digest()
+        synthetic = SyntheticMessageHash(digest=digest).encode()
+        self._messages.clear()
+        self._messages.extend(synthetic)

tigrcorn_security/tls_cipher_policy.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from tigrcorn_core.errors import ConfigError
+
+CIPHER_TLS_AES_128_GCM_SHA256 = 0x1301
+CIPHER_TLS_AES_256_GCM_SHA384 = 0x1302
+
+SUPPORTED_TLS13_CIPHER_SUITES = (
+    CIPHER_TLS_AES_256_GCM_SHA384,
+    CIPHER_TLS_AES_128_GCM_SHA256,
+)
+
+CIPHER_SUITE_NAME_TO_ID = {
+    'TLS_AES_128_GCM_SHA256': CIPHER_TLS_AES_128_GCM_SHA256,
+    'TLS_AES_256_GCM_SHA384': CIPHER_TLS_AES_256_GCM_SHA384,
+}
+
+
+def tls13_cipher_suite_name(cipher_suite: int) -> str:
+    for name, value in CIPHER_SUITE_NAME_TO_ID.items():
+        if value == cipher_suite:
+            return name
+    return f'0x{cipher_suite:04x}'
+
+
+def parse_tls13_cipher_allowlist(value: str | None) -> tuple[int, ...]:
+    if value is None:
+        return ()
+    tokens = [token.strip() for token in value.replace(',', ':').split(':') if token.strip()]
+    if not tokens:
+        raise ConfigError('ssl_ciphers must contain at least one TLS 1.3 cipher suite name')
+    resolved: list[int] = []
+    for token in tokens:
+        if token not in CIPHER_SUITE_NAME_TO_ID:
+            raise ConfigError(f'unsupported TLS 1.3 cipher suite: {token!r}')
+        cipher_suite = CIPHER_SUITE_NAME_TO_ID[token]
+        if cipher_suite not in resolved:
+            resolved.append(cipher_suite)
+    return tuple(resolved)
+
+
+def format_tls13_cipher_allowlist(cipher_suites: tuple[int, ...] | list[int]) -> str:
+    return ':'.join(tls13_cipher_suite_name(cipher_suite) for cipher_suite in cipher_suites)

tigrcorn_security/x509/__init__.py

@@ -0,0 +1,31 @@
+from .path import (
+    CertificatePurpose,
+    CertificateValidationPolicy,
+    RevocationCache,
+    RevocationCacheEntry,
+    RevocationFetchPolicy,
+    RevocationFreshnessPolicy,
+    RevocationMaterial,
+    RevocationMode,
+    VerifiedCertificatePath,
+    load_pem_certificates,
+    verify_certificate_chain,
+    verify_certificate_hostname,
+    verify_certificate_validity,
+)
+
+__all__ = [
+    'CertificatePurpose',
+    'CertificateValidationPolicy',
+    'RevocationCache',
+    'RevocationCacheEntry',
+    'RevocationFetchPolicy',
+    'RevocationFreshnessPolicy',
+    'RevocationMaterial',
+    'RevocationMode',
+    'VerifiedCertificatePath',
+    'load_pem_certificates',
+    'verify_certificate_chain',
+    'verify_certificate_hostname',
+    'verify_certificate_validity',
+]