ratchetkit 1.2.0__py3-none-any.whl

ratchetkit/__init__.py

@@ -0,0 +1,3 @@
+"""ratchetkit - X3DH/PQXDH + Double/Triple Ratchet with pluggable crypto."""
+
+__version__ = "1.2.0"

ratchetkit/algorithms/__init__.py

@@ -0,0 +1 @@
+"""Pluggable crypto primitives: hash, cipher, KEM."""

ratchetkit/algorithms/cipher/__init__.py

@@ -0,0 +1,17 @@
+"""Cipher algorithm classes."""
+
+from ratchetkit.algorithms.cipher.aes128 import Aes128
+from ratchetkit.algorithms.cipher.aes256 import Aes256
+from ratchetkit.algorithms.cipher.base import CipherAlgorithm
+from ratchetkit.algorithms.cipher.camellia128 import Camellia128
+from ratchetkit.algorithms.cipher.camellia256 import Camellia256
+from ratchetkit.algorithms.cipher.chacha20 import ChaCha20
+
+__all__ = [
+    "Aes128",
+    "Aes256",
+    "Camellia128",
+    "Camellia256",
+    "ChaCha20",
+    "CipherAlgorithm",
+]

ratchetkit/algorithms/cipher/aes128.py

@@ -0,0 +1,15 @@
+"""AES-128 cipher algorithm."""
+
+from __future__ import annotations
+
+from cryptography.hazmat.primitives.ciphers import algorithms
+
+from ratchetkit.algorithms.cipher.base import CipherAlgorithm
+
+
+class Aes128(CipherAlgorithm):
+    name = "aes128"
+    key_size = 16
+    block_size = 16
+    nonce_size = 16
+    algorithm = algorithms.AES

ratchetkit/algorithms/cipher/aes256.py

@@ -0,0 +1,15 @@
+"""AES-256 cipher algorithm."""
+
+from __future__ import annotations
+
+from cryptography.hazmat.primitives.ciphers import algorithms
+
+from ratchetkit.algorithms.cipher.base import CipherAlgorithm
+
+
+class Aes256(CipherAlgorithm):
+    name = "aes256"
+    key_size = 32
+    block_size = 16
+    nonce_size = 16
+    algorithm = algorithms.AES

ratchetkit/algorithms/cipher/base.py

@@ -0,0 +1,65 @@
+"""Base class for pluggable symmetric ciphers."""
+
+from __future__ import annotations
+
+from abc import ABC
+from typing import Any
+
+from cryptography.hazmat.primitives.ciphers import Cipher, modes
+
+
+class CipherAlgorithm(ABC):
+    """Symmetric cipher used when deriving and applying MessageKeys.
+
+    Block ciphers always run in CTR (single-use message keys). Stream
+    ciphers (ChaCha20) take the IV as the nonce directly.
+    """
+
+    name: str
+    key_size: int
+    block_size: int
+    nonce_size: int
+    algorithm: Any  # hazmat algorithms.* class
+    is_stream: bool = False
+
+    @classmethod
+    def iv_size(cls) -> int:
+        if cls.is_stream:
+            # cryptography ChaCha20 uses 16-byte nonce (4-byte counter + 12-byte nonce)
+            return cls.nonce_size
+        # Only CTR is used for block ciphers; IV length is the block size.
+        return cls.block_size
+
+    @classmethod
+    def encrypt(cls, key: bytes, iv: bytes, plaintext: bytes) -> bytes:
+        if len(key) != cls.key_size:
+            raise ValueError(
+                f"{cls.name} key must be {cls.key_size} bytes, got {len(key)}"
+            )
+        if len(iv) != cls.iv_size():
+            raise ValueError(
+                f"{cls.name} iv must be {cls.iv_size()} bytes, got {len(iv)}"
+            )
+        if cls.is_stream:
+            cipher = Cipher(cls.algorithm(key, iv), mode=None)
+        else:
+            cipher = Cipher(cls.algorithm(key), modes.CTR(iv))
+        encryptor = cipher.encryptor()
+        return encryptor.update(plaintext) + encryptor.finalize()
+
+    @classmethod
+    def decrypt(cls, key: bytes, iv: bytes, ciphertext: bytes) -> bytes:
+        if len(key) != cls.key_size:
+            raise ValueError(
+                f"{cls.name} key must be {cls.key_size} bytes, got {len(key)}"
+            )
+        if len(iv) != cls.iv_size():
+            raise ValueError(
+                f"{cls.name} iv must be {cls.iv_size()} bytes, got {len(iv)}"
+            )
+        if cls.is_stream:
+            cipher = Cipher(cls.algorithm(key, iv), mode=None)
+        else:
+            cipher = Cipher(cls.algorithm(key), modes.CTR(iv))
+        decryptor = cipher.decryptor()
+        return decryptor.update(ciphertext) + decryptor.finalize()

ratchetkit/algorithms/cipher/camellia128.py

@@ -0,0 +1,18 @@
+"""Camellia-128 cipher algorithm."""
+
+from __future__ import annotations
+
+try:
+    from cryptography.hazmat.decrepit.ciphers.algorithms import Camellia
+except ImportError:  # pragma: no cover - older cryptography
+    from cryptography.hazmat.primitives.ciphers.algorithms import Camellia
+
+from ratchetkit.algorithms.cipher.base import CipherAlgorithm
+
+
+class Camellia128(CipherAlgorithm):
+    name = "camellia128"
+    key_size = 16
+    block_size = 16
+    nonce_size = 16
+    algorithm = Camellia

ratchetkit/algorithms/cipher/camellia256.py

@@ -0,0 +1,18 @@
+"""Camellia-256 cipher algorithm."""
+
+from __future__ import annotations
+
+try:
+    from cryptography.hazmat.decrepit.ciphers.algorithms import Camellia
+except ImportError:  # pragma: no cover - older cryptography
+    from cryptography.hazmat.primitives.ciphers.algorithms import Camellia
+
+from ratchetkit.algorithms.cipher.base import CipherAlgorithm
+
+
+class Camellia256(CipherAlgorithm):
+    name = "camellia256"
+    key_size = 32
+    block_size = 16
+    nonce_size = 16
+    algorithm = Camellia

ratchetkit/algorithms/cipher/chacha20.py

@@ -0,0 +1,17 @@
+"""ChaCha20 stream cipher algorithm."""
+
+from __future__ import annotations
+
+from cryptography.hazmat.primitives.ciphers import algorithms
+
+from ratchetkit.algorithms.cipher.base import CipherAlgorithm
+
+
+class ChaCha20(CipherAlgorithm):
+    name = "chacha20"
+    key_size = 32
+    block_size = 1
+    # cryptography ChaCha20 uses 16-byte nonce (4-byte counter + 12-byte nonce)
+    nonce_size = 16
+    algorithm = algorithms.ChaCha20
+    is_stream = True

ratchetkit/algorithms/hash/__init__.py

@@ -0,0 +1,17 @@
+"""Hash algorithm classes."""
+
+from ratchetkit.algorithms.hash.base import HashAlgorithm
+from ratchetkit.algorithms.hash.blake2b import Blake2b
+from ratchetkit.algorithms.hash.sha256 import Sha256
+from ratchetkit.algorithms.hash.sha384 import Sha384
+from ratchetkit.algorithms.hash.sha3256 import Sha3256
+from ratchetkit.algorithms.hash.sha512 import Sha512
+
+__all__ = [
+    "Blake2b",
+    "HashAlgorithm",
+    "Sha256",
+    "Sha384",
+    "Sha3256",
+    "Sha512",
+]

ratchetkit/algorithms/hash/base.py

@@ -0,0 +1,30 @@
+"""Base class for pluggable hash algorithms."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from cryptography.hazmat.primitives import hashes
+
+
+class HashAlgorithm(ABC):
+    """Hashlib-compatible digest used for HKDF, HMAC, and signature digests."""
+
+    name: str
+    digest_size: int
+
+    @classmethod
+    @abstractmethod
+    def new(cls, data: bytes = b"") -> Any:
+        """Return a hashlib-style digest object."""
+
+    @classmethod
+    @abstractmethod
+    def constructor(cls):
+        """Return the hashlib constructor (for hmac / HKDF)."""
+
+    @classmethod
+    @abstractmethod
+    def hazmat(cls) -> hashes.HashAlgorithm:
+        """cryptography.hazmat hash for ECDSA / RSA-PSS."""

ratchetkit/algorithms/hash/blake2b.py

@@ -0,0 +1,26 @@
+"""BLAKE2b hash algorithm (64-byte digest)."""
+
+from __future__ import annotations
+
+import hashlib
+
+from cryptography.hazmat.primitives import hashes
+
+from ratchetkit.algorithms.hash.base import HashAlgorithm
+
+
+class Blake2b(HashAlgorithm):
+    name = "blake2b"
+    digest_size = 64
+
+    @classmethod
+    def new(cls, data: bytes = b""):
+        return hashlib.blake2b(data)
+
+    @classmethod
+    def constructor(cls):
+        return hashlib.blake2b
+
+    @classmethod
+    def hazmat(cls) -> hashes.HashAlgorithm:
+        return hashes.BLAKE2b(64)

ratchetkit/algorithms/hash/sha256.py

@@ -0,0 +1,26 @@
+"""SHA-256 hash algorithm."""
+
+from __future__ import annotations
+
+import hashlib
+
+from cryptography.hazmat.primitives import hashes
+
+from ratchetkit.algorithms.hash.base import HashAlgorithm
+
+
+class Sha256(HashAlgorithm):
+    name = "sha256"
+    digest_size = 32
+
+    @classmethod
+    def new(cls, data: bytes = b""):
+        return hashlib.sha256(data)
+
+    @classmethod
+    def constructor(cls):
+        return hashlib.sha256
+
+    @classmethod
+    def hazmat(cls) -> hashes.HashAlgorithm:
+        return hashes.SHA256()

ratchetkit/algorithms/hash/sha3256.py

@@ -0,0 +1,26 @@
+"""SHA3-256 hash algorithm."""
+
+from __future__ import annotations
+
+import hashlib
+
+from cryptography.hazmat.primitives import hashes
+
+from ratchetkit.algorithms.hash.base import HashAlgorithm
+
+
+class Sha3256(HashAlgorithm):
+    name = "sha3_256"
+    digest_size = 32
+
+    @classmethod
+    def new(cls, data: bytes = b""):
+        return hashlib.sha3_256(data)
+
+    @classmethod
+    def constructor(cls):
+        return hashlib.sha3_256
+
+    @classmethod
+    def hazmat(cls) -> hashes.HashAlgorithm:
+        return hashes.SHA3_256()

ratchetkit/algorithms/hash/sha384.py

@@ -0,0 +1,26 @@
+"""SHA-384 hash algorithm."""
+
+from __future__ import annotations
+
+import hashlib
+
+from cryptography.hazmat.primitives import hashes
+
+from ratchetkit.algorithms.hash.base import HashAlgorithm
+
+
+class Sha384(HashAlgorithm):
+    name = "sha384"
+    digest_size = 48
+
+    @classmethod
+    def new(cls, data: bytes = b""):
+        return hashlib.sha384(data)
+
+    @classmethod
+    def constructor(cls):
+        return hashlib.sha384
+
+    @classmethod
+    def hazmat(cls) -> hashes.HashAlgorithm:
+        return hashes.SHA384()

ratchetkit/algorithms/hash/sha512.py

@@ -0,0 +1,26 @@
+"""SHA-512 hash algorithm."""
+
+from __future__ import annotations
+
+import hashlib
+
+from cryptography.hazmat.primitives import hashes
+
+from ratchetkit.algorithms.hash.base import HashAlgorithm
+
+
+class Sha512(HashAlgorithm):
+    name = "sha512"
+    digest_size = 64
+
+    @classmethod
+    def new(cls, data: bytes = b""):
+        return hashlib.sha512(data)
+
+    @classmethod
+    def constructor(cls):
+        return hashlib.sha512
+
+    @classmethod
+    def hazmat(cls) -> hashes.HashAlgorithm:
+        return hashes.SHA512()

ratchetkit/algorithms/kem/__init__.py

@@ -0,0 +1,12 @@
+"""KEM / key-exchange algorithm classes.
+
+Import concrete backends from their modules (``ratchetkit.algorithms.kem.x25519`` and
+so on). This package does not re-export them: ``suite`` already imports the
+classes, and a package-level import cycle otherwise forms through ``keys``.
+"""
+
+from ratchetkit.algorithms.kem.base import KemBackend
+
+__all__ = [
+    "KemBackend",
+]

ratchetkit/algorithms/kem/base.py

@@ -0,0 +1,63 @@
+"""KEM backend interface for ExtendedTripleDiffieHellman and the Double Ratchet."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ratchetkit.algorithms.hash.base import HashAlgorithm
+    from ratchetkit.keys.keypair import (
+        KeyPair,
+        PrivateKey,
+        PublicKey,
+        SigningKeyPair,
+        SigningPrivateKey,
+        SigningPublicKey,
+    )
+
+
+class KemBackend(ABC):
+    """Key-encapsulation strategy used by ExtendedTripleDiffieHellman and the Double Ratchet."""
+
+    name: str
+    supports_dh: bool = False
+
+    @abstractmethod
+    def generate_keypair(self) -> KeyPair:
+        ...
+
+    @abstractmethod
+    def encapsulate(self, their_public: PublicKey) -> tuple[bytes, bytes]:
+        """Return ``(shared_secret, ciphertext)``."""
+
+    @abstractmethod
+    def decapsulate(self, our_private: PrivateKey, ciphertext: bytes) -> bytes:
+        ...
+
+    @abstractmethod
+    def generate_signing_keypair(self) -> SigningKeyPair:
+        ...
+
+    @abstractmethod
+    def sign(
+        self,
+        private: SigningPrivateKey,
+        message: bytes,
+        digest: type[HashAlgorithm],
+    ) -> bytes:
+        ...
+
+    @abstractmethod
+    def verify(
+        self,
+        public: SigningPublicKey,
+        message: bytes,
+        signature: bytes,
+        digest: type[HashAlgorithm],
+    ) -> None:
+        """Raise :class:`~ratchetkit.errors.InvalidSignature` on failure."""
+
+    def dh(self, our_private: PrivateKey, their_public: PublicKey) -> bytes:
+        """Optional mutual DH. Only implemented by DH-capable backends."""
+        raise NotImplementedError(f"{self.name} does not support mutual DH")

ratchetkit/algorithms/kem/ec_base.py

@@ -0,0 +1,104 @@
+"""Shared NIST elliptic-curve ECDH + ECDSA implementation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.serialization import Encoding, 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 EcKem(KemBackend):
+    """NIST elliptic-curve ECDH-as-KEM + ECDSA backend base."""
+
+    name: str
+    curve: ec.EllipticCurve
+    supports_dh = True
+
+    def generate_keypair(self) -> KeyPair:
+        private = ec.generate_private_key(self.curve)
+        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]:
+        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 = self.decode_private(our_private.data)
+            public = self.decode_public(their_public.data)
+            shared = private.exchange(ec.ECDH(), public)
+        except Exception as exc:
+            raise InvalidKey(
+                f"{self.name} ECDH failed (invalid public key)"
+            ) from exc
+        if not any(shared):
+            raise InvalidKey(f"{self.name} ECDH produced an all-zero shared secret")
+        return shared
+
+    def generate_signing_keypair(self) -> SigningKeyPair:
+        # Re-use the same curve for identity signing (ECDSA).
+        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)
+        return key.sign(message, ec.ECDSA(digest.hazmat()))
+
+    def verify(
+        self,
+        public: SigningPublicKey,
+        message: bytes,
+        signature: bytes,
+        digest: type[HashAlgorithm],
+    ) -> None:
+        key = self.decode_public(public.data)
+        try:
+            key.verify(signature, message, ec.ECDSA(digest.hazmat()))
+        except Exception as exc:
+            raise InvalidSignature("ECDSA verification failed") from exc
+
+    @staticmethod
+    def encode_public(key: ec.EllipticCurvePublicKey) -> bytes:
+        return key.public_bytes(Encoding.X962, PublicFormat.UncompressedPoint)
+
+    def encode_private(self, key: ec.EllipticCurvePrivateKey) -> bytes:
+        numbers = key.private_numbers()
+        byte_length = (self.curve.key_size + 7) // 8
+        return numbers.private_value.to_bytes(byte_length, "big")
+
+    def decode_private(self, data: bytes) -> ec.EllipticCurvePrivateKey:
+        value = int.from_bytes(data, "big")
+        return ec.derive_private_key(value, self.curve)
+
+    def decode_public(self, data: bytes) -> ec.EllipticCurvePublicKey:
+        return ec.EllipticCurvePublicKey.from_encoded_point(self.curve, data)

ratchetkit/algorithms/kem/mlkem1024.py

@@ -0,0 +1,15 @@
+"""ML-KEM-1024 + ML-DSA-87 (NIST category 5)."""
+
+from __future__ import annotations
+
+from cryptography.hazmat.primitives.asymmetric import mldsa, mlkem
+
+from ratchetkit.algorithms.kem.mlkem_base import MlkemBackend
+
+
+class Mlkem1024(MlkemBackend):
+    name = "mlkem1024"
+    kem_private_cls = mlkem.MLKEM1024PrivateKey
+    kem_public_cls = mlkem.MLKEM1024PublicKey
+    dsa_private_cls = mldsa.MLDSA87PrivateKey
+    dsa_public_cls = mldsa.MLDSA87PublicKey

ratchetkit/algorithms/kem/mlkem768.py

@@ -0,0 +1,15 @@
+"""ML-KEM-768 + ML-DSA-65 (NIST category 3)."""
+
+from __future__ import annotations
+
+from cryptography.hazmat.primitives.asymmetric import mldsa, mlkem
+
+from ratchetkit.algorithms.kem.mlkem_base import MlkemBackend
+
+
+class Mlkem768(MlkemBackend):
+    name = "mlkem768"
+    kem_private_cls = mlkem.MLKEM768PrivateKey
+    kem_public_cls = mlkem.MLKEM768PublicKey
+    dsa_private_cls = mldsa.MLDSA65PrivateKey
+    dsa_public_cls = mldsa.MLDSA65PublicKey

ratchetkit/algorithms/kem/mlkem_base.py

@@ -0,0 +1,97 @@
+"""Shared ML-KEM encapsulation + ML-DSA signatures (FIPS 203 / 204)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+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 MlkemBackend(KemBackend):
+    """Post-quantum KEM-only backend: ML-KEM for agreement, ML-DSA for identity.
+
+    Private keys are stored as the FIPS seed (``private_bytes_raw`` /
+    ``from_seed_bytes``), not the expanded secret key.
+    """
+
+    name: str
+    supports_dh = False
+    # cryptography class objects, set on each concrete subclass
+    kem_private_cls: Any
+    kem_public_cls: Any
+    dsa_private_cls: Any
+    dsa_public_cls: Any
+
+    def generate_keypair(self) -> KeyPair:
+        private = self.kem_private_cls.generate()
+        return KeyPair(
+            public=PublicKey(
+                private.public_key().public_bytes_raw(),
+                self.name,
+            ),
+            private=PrivateKey(
+                private.private_bytes_raw(),
+                self.name,
+            ),
+        )
+
+    def encapsulate(self, their_public: PublicKey) -> tuple[bytes, bytes]:
+        public = self.kem_public_cls.from_public_bytes(their_public.data)
+        # cryptography returns (shared_secret, ciphertext)
+        secret, ciphertext = public.encapsulate()
+        return secret, ciphertext
+
+    def decapsulate(self, our_private: PrivateKey, ciphertext: bytes) -> bytes:
+        try:
+            private = self.kem_private_cls.from_seed_bytes(our_private.data)
+            return private.decapsulate(ciphertext)
+        except Exception as exc:
+            raise InvalidKey(f"{self.name} decapsulation failed") from exc
+
+    def generate_signing_keypair(self) -> SigningKeyPair:
+        private = self.dsa_private_cls.generate()
+        return SigningKeyPair(
+            public=SigningPublicKey(
+                private.public_key().public_bytes_raw(),
+                self.name,
+            ),
+            private=SigningPrivateKey(
+                private.private_bytes_raw(),
+                self.name,
+            ),
+        )
+
+    def sign(
+        self,
+        private: SigningPrivateKey,
+        message: bytes,
+        digest: type[HashAlgorithm],
+    ) -> bytes:
+        # ML-DSA is a pure signature scheme; digest is unused (suite still has one).
+        key = self.dsa_private_cls.from_seed_bytes(private.data)
+        return key.sign(message)
+
+    def verify(
+        self,
+        public: SigningPublicKey,
+        message: bytes,
+        signature: bytes,
+        digest: type[HashAlgorithm],
+    ) -> None:
+        key = self.dsa_public_cls.from_public_bytes(public.data)
+        try:
+            key.verify(signature, message)
+        except Exception as exc:
+            raise InvalidSignature(f"{self.name} ML-DSA verification failed") from exc