ratchetkit 1.2.0__py3-none-any.whl

ratchetkit/algorithms/kem/rsa2048.py

@@ -0,0 +1,10 @@
+"""RSA-2048 OAEP encapsulation + RSA-PSS signatures."""
+
+from __future__ import annotations
+
+from ratchetkit.algorithms.kem.rsa_base import RsaKem
+
+
+class Rsa2048(RsaKem):
+    name = "rsa2048"
+    key_size = 2048

ratchetkit/algorithms/kem/rsa4096.py

@@ -0,0 +1,10 @@
+"""RSA-4096 OAEP encapsulation + RSA-PSS signatures."""
+
+from __future__ import annotations
+
+from ratchetkit.algorithms.kem.rsa_base import RsaKem
+
+
+class Rsa4096(RsaKem):
+    name = "rsa4096"
+    key_size = 4096

ratchetkit/algorithms/kem/rsa_base.py

@@ -0,0 +1,151 @@
+"""Shared RSA-OAEP encapsulation + RSA-PSS signatures."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding, rsa, utils
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+)
+
+from ratchetkit.errors import InvalidKey, InvalidSignature
+from ratchetkit.algorithms.kem.base import KemBackend
+from ratchetkit.keys.keypair import (
+    KeyPair,
+    PrivateKey,
+    PublicKey,
+    SigningKeyPair,
+    SigningPrivateKey,
+    SigningPublicKey,
+)
+
+if TYPE_CHECKING:
+    from ratchetkit.algorithms.hash.base import HashAlgorithm
+
+
+class RsaKem(KemBackend):
+    """RSA-OAEP encapsulation + RSA-PSS signatures backend base."""
+
+    name: str
+    key_size: int
+    supports_dh = False
+    secret_size = 32
+
+    def generate_keypair(self) -> KeyPair:
+        private = rsa.generate_private_key(
+            public_exponent=65537,
+            key_size=self.key_size,
+        )
+        return KeyPair(
+            public=PublicKey(self.encode_public(private.public_key()), self.name),
+            private=PrivateKey(self.encode_private(private), self.name),
+        )
+
+    def encapsulate(self, their_public: PublicKey) -> tuple[bytes, bytes]:
+        public = self.decode_public(their_public.data)
+        secret = os.urandom(self.secret_size)
+        ciphertext = public.encrypt(
+            secret,
+            padding.OAEP(
+                mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                algorithm=hashes.SHA256(),
+                label=None,
+            ),
+        )
+        return secret, ciphertext
+
+    def decapsulate(self, our_private: PrivateKey, ciphertext: bytes) -> bytes:
+        private = self.decode_private(our_private.data)
+        try:
+            return private.decrypt(
+                ciphertext,
+                padding.OAEP(
+                    mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                    algorithm=hashes.SHA256(),
+                    label=None,
+                ),
+            )
+        except Exception as exc:
+            raise InvalidKey("RSA-OAEP decapsulation failed") from exc
+
+    def generate_signing_keypair(self) -> SigningKeyPair:
+        pair = self.generate_keypair()
+        return SigningKeyPair(
+            public=SigningPublicKey(pair.public.data, self.name),
+            private=SigningPrivateKey(pair.private.data, self.name),
+        )
+
+    def sign(
+        self,
+        private: SigningPrivateKey,
+        message: bytes,
+        digest: type[HashAlgorithm],
+    ) -> bytes:
+        key = self.decode_private(private.data)
+        algorithm = digest.hazmat()
+        hasher = hashes.Hash(algorithm)
+        hasher.update(message)
+        return key.sign(
+            hasher.finalize(),
+            padding.PSS(
+                mgf=padding.MGF1(algorithm),
+                salt_length=padding.PSS.MAX_LENGTH,
+            ),
+            utils.Prehashed(algorithm),
+        )
+
+    def verify(
+        self,
+        public: SigningPublicKey,
+        message: bytes,
+        signature: bytes,
+        digest: type[HashAlgorithm],
+    ) -> None:
+        key = self.decode_public(public.data)
+        algorithm = digest.hazmat()
+        hasher = hashes.Hash(algorithm)
+        hasher.update(message)
+        try:
+            key.verify(
+                signature,
+                hasher.finalize(),
+                padding.PSS(
+                    mgf=padding.MGF1(algorithm),
+                    salt_length=padding.PSS.MAX_LENGTH,
+                ),
+                utils.Prehashed(algorithm),
+            )
+        except Exception as exc:
+            raise InvalidSignature("RSA-PSS verification failed") from exc
+
+    @staticmethod
+    def encode_public(key: rsa.RSAPublicKey) -> bytes:
+        return key.public_bytes(Encoding.DER, PublicFormat.SubjectPublicKeyInfo)
+
+    @staticmethod
+    def encode_private(key: rsa.RSAPrivateKey) -> bytes:
+        return key.private_bytes(
+            Encoding.DER,
+            PrivateFormat.PKCS8,
+            NoEncryption(),
+        )
+
+    @staticmethod
+    def decode_public(data: bytes) -> rsa.RSAPublicKey:
+        key = serialization.load_der_public_key(data)
+        if not isinstance(key, rsa.RSAPublicKey):
+            raise InvalidKey("expected RSA public key")
+        return key
+
+    @staticmethod
+    def decode_private(data: bytes) -> rsa.RSAPrivateKey:
+        key = serialization.load_der_private_key(data, password=None)
+        if not isinstance(key, rsa.RSAPrivateKey):
+            raise InvalidKey("expected RSA private key")
+        return key

ratchetkit/algorithms/kem/secp256r1.py

@@ -0,0 +1,12 @@
+"""SECP256R1 ECDH-as-KEM + ECDSA signatures."""
+
+from __future__ import annotations
+
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from ratchetkit.algorithms.kem.ec_base import EcKem
+
+
+class Secp256r1(EcKem):
+    name = "secp256r1"
+    curve = ec.SECP256R1()

ratchetkit/algorithms/kem/secp384r1.py

@@ -0,0 +1,12 @@
+"""SECP384R1 ECDH-as-KEM + ECDSA signatures."""
+
+from __future__ import annotations
+
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from ratchetkit.algorithms.kem.ec_base import EcKem
+
+
+class Secp384r1(EcKem):
+    name = "secp384r1"
+    curve = ec.SECP384R1()

ratchetkit/algorithms/kem/secp521r1.py

@@ -0,0 +1,12 @@
+"""SECP521R1 ECDH-as-KEM + ECDSA signatures."""
+
+from __future__ import annotations
+
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from ratchetkit.algorithms.kem.ec_base import EcKem
+
+
+class Secp521r1(EcKem):
+    name = "secp521r1"
+    curve = ec.SECP521R1()

ratchetkit/algorithms/kem/x25519.py

@@ -0,0 +1,107 @@
+"""X25519 DH-as-KEM + Ed25519 signatures."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cryptography.hazmat.primitives.asymmetric import ed25519, x25519
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+)
+
+from ratchetkit.errors import InvalidKey, InvalidSignature
+from ratchetkit.algorithms.kem.base import KemBackend
+from ratchetkit.keys.keypair import (
+    KeyPair,
+    PrivateKey,
+    PublicKey,
+    SigningKeyPair,
+    SigningPrivateKey,
+    SigningPublicKey,
+)
+
+if TYPE_CHECKING:
+    from ratchetkit.algorithms.hash.base import HashAlgorithm
+
+
+class X25519(KemBackend):
+    name = "x25519"
+    supports_dh = True
+
+    def generate_keypair(self) -> KeyPair:
+        private = x25519.X25519PrivateKey.generate()
+        return KeyPair(
+            public=PublicKey(
+                private.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw),
+                self.name,
+            ),
+            private=PrivateKey(
+                private.private_bytes(
+                    Encoding.Raw,
+                    PrivateFormat.Raw,
+                    NoEncryption(),
+                ),
+                self.name,
+            ),
+        )
+
+    def encapsulate(self, their_public: PublicKey) -> tuple[bytes, bytes]:
+        ephemeral = self.generate_keypair()
+        secret = self.dh(ephemeral.private, their_public)
+        return secret, ephemeral.public.data
+
+    def decapsulate(self, our_private: PrivateKey, ciphertext: bytes) -> bytes:
+        return self.dh(our_private, PublicKey(ciphertext, self.name))
+
+    def dh(self, our_private: PrivateKey, their_public: PublicKey) -> bytes:
+        try:
+            private = x25519.X25519PrivateKey.from_private_bytes(our_private.data)
+            public = x25519.X25519PublicKey.from_public_bytes(their_public.data)
+            shared = private.exchange(public)
+        except Exception as exc:
+            raise InvalidKey("X25519 DH failed (invalid or low-order public key)") from exc
+        if not any(shared):
+            raise InvalidKey("X25519 DH produced an all-zero shared secret")
+        return shared
+
+    def generate_signing_keypair(self) -> SigningKeyPair:
+        private = ed25519.Ed25519PrivateKey.generate()
+        return SigningKeyPair(
+            public=SigningPublicKey(
+                private.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw),
+                self.name,
+            ),
+            private=SigningPrivateKey(
+                private.private_bytes(
+                    Encoding.Raw,
+                    PrivateFormat.Raw,
+                    NoEncryption(),
+                ),
+                self.name,
+            ),
+        )
+
+    def sign(
+        self,
+        private: SigningPrivateKey,
+        message: bytes,
+        digest: type[HashAlgorithm],
+    ) -> bytes:
+        key = ed25519.Ed25519PrivateKey.from_private_bytes(private.data)
+        return key.sign(message)
+
+    def verify(
+        self,
+        public: SigningPublicKey,
+        message: bytes,
+        signature: bytes,
+        digest: type[HashAlgorithm],
+    ) -> None:
+        key = ed25519.Ed25519PublicKey.from_public_bytes(public.data)
+        try:
+            key.verify(signature, message)
+        except Exception as exc:
+            raise InvalidSignature("Ed25519 verification failed") from exc

ratchetkit/algorithms/kem/x448.py

@@ -0,0 +1,107 @@
+"""X448 DH-as-KEM + Ed448 signatures."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cryptography.hazmat.primitives.asymmetric import ed448, x448
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+)
+
+from ratchetkit.errors import InvalidKey, InvalidSignature
+from ratchetkit.algorithms.kem.base import KemBackend
+from ratchetkit.keys.keypair import (
+    KeyPair,
+    PrivateKey,
+    PublicKey,
+    SigningKeyPair,
+    SigningPrivateKey,
+    SigningPublicKey,
+)
+
+if TYPE_CHECKING:
+    from ratchetkit.algorithms.hash.base import HashAlgorithm
+
+
+class X448(KemBackend):
+    name = "x448"
+    supports_dh = True
+
+    def generate_keypair(self) -> KeyPair:
+        private = x448.X448PrivateKey.generate()
+        return KeyPair(
+            public=PublicKey(
+                private.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw),
+                self.name,
+            ),
+            private=PrivateKey(
+                private.private_bytes(
+                    Encoding.Raw,
+                    PrivateFormat.Raw,
+                    NoEncryption(),
+                ),
+                self.name,
+            ),
+        )
+
+    def encapsulate(self, their_public: PublicKey) -> tuple[bytes, bytes]:
+        ephemeral = self.generate_keypair()
+        secret = self.dh(ephemeral.private, their_public)
+        return secret, ephemeral.public.data
+
+    def decapsulate(self, our_private: PrivateKey, ciphertext: bytes) -> bytes:
+        return self.dh(our_private, PublicKey(ciphertext, self.name))
+
+    def dh(self, our_private: PrivateKey, their_public: PublicKey) -> bytes:
+        try:
+            private = x448.X448PrivateKey.from_private_bytes(our_private.data)
+            public = x448.X448PublicKey.from_public_bytes(their_public.data)
+            shared = private.exchange(public)
+        except Exception as exc:
+            raise InvalidKey("X448 DH failed (invalid or low-order public key)") from exc
+        if not any(shared):
+            raise InvalidKey("X448 DH produced an all-zero shared secret")
+        return shared
+
+    def generate_signing_keypair(self) -> SigningKeyPair:
+        private = ed448.Ed448PrivateKey.generate()
+        return SigningKeyPair(
+            public=SigningPublicKey(
+                private.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw),
+                self.name,
+            ),
+            private=SigningPrivateKey(
+                private.private_bytes(
+                    Encoding.Raw,
+                    PrivateFormat.Raw,
+                    NoEncryption(),
+                ),
+                self.name,
+            ),
+        )
+
+    def sign(
+        self,
+        private: SigningPrivateKey,
+        message: bytes,
+        digest: type[HashAlgorithm],
+    ) -> bytes:
+        key = ed448.Ed448PrivateKey.from_private_bytes(private.data)
+        return key.sign(message)
+
+    def verify(
+        self,
+        public: SigningPublicKey,
+        message: bytes,
+        signature: bytes,
+        digest: type[HashAlgorithm],
+    ) -> None:
+        key = ed448.Ed448PublicKey.from_public_bytes(public.data)
+        try:
+            key.verify(signature, message)
+        except Exception as exc:
+            raise InvalidSignature("Ed448 verification failed") from exc

ratchetkit/errors.py

@@ -0,0 +1,61 @@
+"""Protocol and cryptographic error types."""
+
+
+class RatchetError(Exception):
+    """Base error for ratchetkit."""
+
+
+class InvalidMessage(RatchetError):
+    """Ciphertext is malformed, truncated, or fails authentication."""
+
+
+class DuplicateMessage(RatchetError):
+    """Message key was already consumed (replay or already-delivered)."""
+
+    def __init__(self, chain_index: int, counter: int):
+        self.chain_index = chain_index
+        self.counter = counter
+        super().__init__(
+            f"duplicate message: chain_index={chain_index}, counter={counter}"
+        )
+
+
+class TooFarInFuture(RatchetError):
+    """Message counter exceeds the allowed forward-jump limit."""
+
+    def __init__(self, chain_index: int, counter: int, limit: int):
+        self.chain_index = chain_index
+        self.counter = counter
+        self.limit = limit
+        super().__init__(
+            f"message too far ahead: index={chain_index}, "
+            f"counter={counter}, limit={limit}"
+        )
+
+
+class TooManySkippedKeys(RatchetError):
+    """Skipped-message cache would exceed its hard size cap.
+
+    Raising (instead of silently dropping keys) avoids permanent loss of
+    delayed messages and matches Double Ratchet §3.1 / §8.4 guidance that
+    MKSKIPPED must bound stored elements.
+    """
+
+    def __init__(self, size: int, limit: int):
+        self.size = size
+        self.limit = limit
+        super().__init__(
+            f"too many skipped message keys: size={size}, limit={limit}"
+        )
+
+
+class InvalidKey(RatchetError):
+    """Key material is missing, wrong length, or fails verification."""
+
+
+class InvalidSignature(RatchetError):
+    """Signed prekey or initiator signature failed verification."""
+
+
+class SerializationError(RatchetError):
+    """Blob is truncated, version-mismatched, or otherwise unreadable."""

ratchetkit/handshake/__init__.py

@@ -0,0 +1,15 @@
+"""X3DH and PQXDH key agreement."""
+
+from ratchetkit.handshake.message import InitialMessage
+from ratchetkit.handshake.pqxdh import PostQuantumExtendedDiffieHellman
+from ratchetkit.handshake.x3dh import (
+    ExtendedTripleDiffieHellman,
+    ExtendedTripleDiffieHellmanResult,
+)
+
+__all__ = [
+    "InitialMessage",
+    "ExtendedTripleDiffieHellman",
+    "ExtendedTripleDiffieHellmanResult",
+    "PostQuantumExtendedDiffieHellman",
+]

ratchetkit/handshake/message.py

@@ -0,0 +1,177 @@
+"""Initial handshake message carried from initiator to responder (X3DH / PQXDH)."""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from ratchetkit.errors import SerializationError
+from ratchetkit.keys.keypair import PublicKey, SigningPublicKey
+from ratchetkit.packing import (
+    ConstructorId,
+    expect_constructor,
+    pack_constructor,
+)
+
+
+@dataclass
+class InitialMessage:
+    """First message of an X3DH / PQXDH handshake (public half only)."""
+
+    identity_signing: SigningPublicKey
+    identity_agreement: PublicKey | None
+    ephemeral_public: PublicKey
+    # For KEM-only suites: encapsulations to SPK / OPK (optional trailing).
+    kem_ciphertexts: tuple[bytes, ...]
+    signed_prekey_id: int
+    one_time_prekey_id: int | None
+    signature: bytes
+    # Optional first ratchet public used to seed the Double Ratchet.
+    ratchet_public: bytes | None = None
+    # PQXDH: encapsulation to the peer's signed PQ prekey.
+    pq_prekey_id: int | None = None
+    pq_ciphertext: bytes | None = None
+
+    CONSTRUCTOR_ID = ConstructorId.INITIAL_MESSAGE
+
+    def to_bytes(self) -> bytes:
+        parts = [
+            pack_constructor(self.CONSTRUCTOR_ID),
+            self.encode_field(self.identity_signing.data),
+            self.encode_field(self.identity_signing.algorithm.encode("ascii")),
+        ]
+        if self.identity_agreement is not None:
+            parts.extend(
+                [
+                    b"\x01",
+                    self.encode_field(self.identity_agreement.data),
+                    self.encode_field(
+                        self.identity_agreement.algorithm.encode("ascii")
+                    ),
+                ]
+            )
+        else:
+            parts.append(b"\x00")
+        parts.extend(
+            [
+                self.encode_field(self.ephemeral_public.data),
+                self.encode_field(self.ephemeral_public.algorithm.encode("ascii")),
+                bytes([len(self.kem_ciphertexts)]),
+            ]
+        )
+        for ct in self.kem_ciphertexts:
+            parts.append(self.encode_field(ct))
+        parts.append(struct.pack(">I", self.signed_prekey_id))
+        if self.one_time_prekey_id is None:
+            parts.append(b"\x00")
+        else:
+            parts.extend([b"\x01", struct.pack(">I", self.one_time_prekey_id)])
+        parts.append(self.encode_field(self.signature))
+        if self.ratchet_public is None:
+            parts.append(b"\x00")
+        else:
+            parts.extend([b"\x01", self.encode_field(self.ratchet_public)])
+        if self.pq_ciphertext is None:
+            parts.append(b"\x00")
+        else:
+            parts.extend(
+                [
+                    b"\x01",
+                    struct.pack(">I", self.pq_prekey_id or 0),
+                    self.encode_field(self.pq_ciphertext),
+                ]
+            )
+        return b"".join(parts)
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> InitialMessage:
+        view = memoryview(data)
+        if not view:
+            raise SerializationError("empty initial message")
+        offset = expect_constructor(view, cls.CONSTRUCTOR_ID)
+
+        identity_data, offset = cls.read_field(view, offset)
+        identity_alg, offset = cls.read_field(view, offset)
+        identity_alg = identity_alg.decode("ascii")
+        has_agreement = view[offset]
+        offset += 1
+        identity_agreement = None
+        if has_agreement:
+            agreement_data, offset = cls.read_field(view, offset)
+            agreement_alg, offset = cls.read_field(view, offset)
+            identity_agreement = PublicKey(
+                agreement_data,
+                agreement_alg.decode("ascii"),
+            )
+        ephemeral_data, offset = cls.read_field(view, offset)
+        ephemeral_alg, offset = cls.read_field(view, offset)
+        ephemeral_alg = ephemeral_alg.decode("ascii")
+        ct_count = view[offset]
+        offset += 1
+        ciphertexts = []
+        for index in range(ct_count):
+            ct, offset = cls.read_field(view, offset)
+            ciphertexts.append(ct)
+        if offset + 4 > len(view):
+            raise SerializationError("truncated signed prekey id")
+        signed_prekey_id = struct.unpack_from(">I", view, offset)[0]
+        offset += 4
+        has_opk = view[offset]
+        offset += 1
+        one_time_prekey_id = None
+        if has_opk:
+            if offset + 4 > len(view):
+                raise SerializationError("truncated one-time prekey id")
+            one_time_prekey_id = struct.unpack_from(">I", view, offset)[0]
+            offset += 4
+        signature, offset = cls.read_field(view, offset)
+        if offset >= len(view):
+            raise SerializationError("truncated initial message ratchet flag")
+        has_ratchet = view[offset]
+        offset += 1
+        ratchet_public = None
+        if has_ratchet:
+            ratchet_public, offset = cls.read_field(view, offset)
+        pq_prekey_id = None
+        pq_ciphertext = None
+        # Older initial messages omit the PQ flag entirely.
+        if offset < len(view):
+            has_pq = view[offset]
+            offset += 1
+            if has_pq:
+                if offset + 4 > len(view):
+                    raise SerializationError("truncated PQ prekey id")
+                pq_prekey_id = struct.unpack_from(">I", view, offset)[0]
+                offset += 4
+                pq_ciphertext, offset = cls.read_field(view, offset)
+        if offset != len(view):
+            raise SerializationError("trailing bytes in initial message")
+        return cls(
+            identity_signing=SigningPublicKey(identity_data, identity_alg),
+            identity_agreement=identity_agreement,
+            ephemeral_public=PublicKey(ephemeral_data, ephemeral_alg),
+            kem_ciphertexts=tuple(ciphertexts),
+            signed_prekey_id=signed_prekey_id,
+            one_time_prekey_id=one_time_prekey_id,
+            signature=signature,
+            ratchet_public=ratchet_public,
+            pq_prekey_id=pq_prekey_id,
+            pq_ciphertext=pq_ciphertext,
+        )
+
+    @staticmethod
+    def encode_field(value: bytes) -> bytes:
+        if len(value) > 0xFFFF:
+            raise SerializationError("field too large")
+        return struct.pack(">H", len(value)) + value
+
+    @staticmethod
+    def read_field(view: memoryview, offset: int) -> tuple[bytes, int]:
+        if offset + 2 > len(view):
+            raise SerializationError("truncated initial message field")
+        length = struct.unpack_from(">H", view, offset)[0]
+        offset += 2
+        if offset + length > len(view):
+            raise SerializationError("truncated initial message field body")
+        value = bytes(view[offset:offset + length])
+        return value, offset + length