cryptovault-py 0.2.0__py3-none-any.whl

cryptovault/__init__.py

@@ -0,0 +1,97 @@
+# Author: Julian Bolivar
+# Version: 0.2.0
+# Date: 2026-10-16
+"""Authenticated encryption byte-compatible with the ``cryptovault`` Rust crate.
+
+A blob produced here opens with the crate and the other way round, for data
+and for wrapped keys, as long as both sides use the same FEC strategy. The
+payload is sealed with AES-256-GCM-SIV under an HKDF-SHA256 sub-key, with the
+header bound as associated data, and then protected for the channel by one of
+the crate's FEC strategies (see :mod:`cryptovault.fec`).
+
+Example:
+    >>> from cryptovault import CryptoVault, generate_dek
+    >>> vault = CryptoVault.default()
+    >>> key = generate_dek()
+    >>> blob = vault.encrypt_with_key(key, "sk-secret")
+    >>> vault.decrypt_with_key(key, blob)
+    'sk-secret'
+"""
+
+from cryptovault.cipher import Aes256GcmSivCipher, AuthenticatedCipher
+from cryptovault.constants import (
+    ARGON2_M_KIB,
+    ARGON2_P,
+    ARGON2_T,
+    BLOB_VERSION,
+    HEADER_LEN,
+    KEY_LEN,
+    MAX_B64_LEN,
+    MAX_BLOB_LEN,
+    MAX_PLAINTEXT_LEN,
+    NONCE_LEN,
+    RECOMMENDED_MAX_PAYLOAD,
+    RS_BLOCK,
+    RS_DATA,
+    RS_INTERLEAVE_MAX,
+    RS_PARITY,
+    SALT_LEN,
+    TAG_LEN,
+    TERMINATION_OVERHEAD,
+    VITERBI_CHUNK,
+)
+from cryptovault.error import (
+    CipherError,
+    CryptoVaultError,
+    EncodingError,
+    ErrorCorrectionError,
+    InvalidInputError,
+    KeyDerivationError,
+)
+from cryptovault.fec import ConcatenatedFec, ErrorCorrection, NoFec
+from cryptovault.kdf import Argon2Kdf, KeyDerivation
+from cryptovault.vault import (
+    CryptoVault,
+    constant_time_eq,
+    generate_dek,
+    generate_salt,
+)
+
+__all__ = [
+    "ARGON2_M_KIB",
+    "ARGON2_P",
+    "ARGON2_T",
+    "BLOB_VERSION",
+    "HEADER_LEN",
+    "KEY_LEN",
+    "MAX_B64_LEN",
+    "MAX_BLOB_LEN",
+    "MAX_PLAINTEXT_LEN",
+    "NONCE_LEN",
+    "RECOMMENDED_MAX_PAYLOAD",
+    "RS_BLOCK",
+    "RS_DATA",
+    "RS_INTERLEAVE_MAX",
+    "RS_PARITY",
+    "SALT_LEN",
+    "TAG_LEN",
+    "TERMINATION_OVERHEAD",
+    "VITERBI_CHUNK",
+    "Aes256GcmSivCipher",
+    "Argon2Kdf",
+    "AuthenticatedCipher",
+    "CipherError",
+    "ConcatenatedFec",
+    "CryptoVault",
+    "CryptoVaultError",
+    "EncodingError",
+    "ErrorCorrection",
+    "ErrorCorrectionError",
+    "InvalidInputError",
+    "KeyDerivation",
+    "KeyDerivationError",
+    "NoFec",
+    "constant_time_eq",
+    "generate_dek",
+    "generate_salt",
+]

cryptovault/_blob.py

@@ -0,0 +1,63 @@
+# Author: Julian Bolivar
+# Version: 0.1.0
+# Date: 2026-10-16
+"""Blob wire layout and the structural checks made before decryption.
+
+Private, as in the crate: the public doors are the vault's methods. Layout::
+
+    protected = version (1) ‖ plaintext_len (u32 LE, 4) ‖ nonce ‖ ciphertext ‖ tag
+    blob      = fec.encode(protected)
+
+Every rejection uses a fixed message that repeats nothing of the input.
+"""
+
+import struct
+from typing import Final
+
+from cryptovault.constants import (
+    BLOB_VERSION,
+    HEADER_LEN,
+    MAX_PLAINTEXT_LEN,
+    NONCE_LEN,
+    TAG_LEN,
+)
+from cryptovault.error import InvalidInputError
+from cryptovault.fec import ErrorCorrection
+
+_MALFORMED: Final = "malformed blob"
+_LEN_FIELD: Final = struct.Struct("<I")
+
+
+def decode_blob(fec: ErrorCorrection, received: bytes) -> tuple[int, int, bytes]:
+    """Undo the FEC layer and split the protected payload, checking structure.
+
+    Checks run in the crate's order: the FEC length gate, then the header
+    length, the version, the declared plaintext length against
+    ``MAX_PLAINTEXT_LEN``, and that length against the bytes received. Bytes
+    after the tag are ignored, as in the crate.
+
+    Args:
+        fec: The strategy that encoded the blob.
+        received: The base64-decoded blob.
+
+    Returns:
+        ``(version, plaintext_len, body)`` with ``body = nonce ‖ ciphertext ‖ tag``.
+
+    Raises:
+        InvalidInputError: ``"malformed blob"`` for a short or inconsistent blob,
+            ``"unsupported blob version"`` for a version other than 1, or the
+            FEC strategy's own rejection.
+    """
+    protected = fec.decode(received, fec.validate_pre_fec(received))
+    if len(protected) < HEADER_LEN:
+        raise InvalidInputError(_MALFORMED)
+    version = protected[0]
+    if version != BLOB_VERSION:
+        raise InvalidInputError("unsupported blob version")
+    (plaintext_len,) = _LEN_FIELD.unpack_from(protected, 1)
+    if plaintext_len > MAX_PLAINTEXT_LEN:
+        raise InvalidInputError(_MALFORMED)
+    protected_len = HEADER_LEN + NONCE_LEN + plaintext_len + TAG_LEN
+    if protected_len > len(protected):
+        raise InvalidInputError(_MALFORMED)
+    return version, plaintext_len, protected[HEADER_LEN:protected_len]

cryptovault/cipher.py

@@ -0,0 +1,138 @@
+# Author: Julian Bolivar
+# Version: 0.1.0
+# Date: 2026-10-16
+"""AEAD strategy: AES-256-GCM-SIV (RFC 8452) from ``cryptography``."""
+
+import os
+from typing import Final, Protocol
+
+from cryptography.exceptions import InvalidTag, UnsupportedAlgorithm
+from cryptography.hazmat.primitives.ciphers.aead import AESGCMSIV
+
+from cryptovault.constants import KEY_LEN, NONCE_LEN
+from cryptovault.error import CipherError
+
+_AUTH_FAILED: Final = "AES-256-GCM-SIV authentication failed"
+
+
+def sample_nonce() -> bytes:
+    """Draw a fresh random nonce from the operating-system CSPRNG.
+
+    Every message gets its own nonce; a counter or a fixed nonce is never used.
+
+    Returns:
+        ``NONCE_LEN`` (12) random bytes.
+
+    Raises:
+        CipherError: If the operating system cannot supply entropy. Weak bytes
+            are never returned instead.
+    """
+    try:
+        return os.urandom(NONCE_LEN)
+    except OSError as exc:
+        raise CipherError(f"OsRng nonce sampling failed: {exc}") from exc
+
+
+class AuthenticatedCipher(Protocol):
+    """AEAD strategy, the crate's ``AuthenticatedCipher`` trait."""
+
+    def encrypt(self, key: bytes, nonce: bytes, aad: bytes, plaintext: bytes) -> bytes:
+        """Encrypt and authenticate ``plaintext`` under ``aad``.
+
+        Args:
+            key: The AEAD key.
+            nonce: The per-message nonce.
+            aad: Associated data, authenticated but not encrypted.
+            plaintext: The data to encrypt.
+
+        Returns:
+            ``ciphertext ‖ tag``.
+
+        Raises:
+            CipherError: If the key or nonce is invalid.
+        """
+        ...
+
+    def decrypt(self, key: bytes, nonce: bytes, aad: bytes, sealed: bytes) -> bytes:
+        """Verify and decrypt ``ciphertext ‖ tag``.
+
+        Args:
+            key: The AEAD key.
+            nonce: The per-message nonce.
+            aad: The associated data the blob was sealed with.
+            sealed: ``ciphertext ‖ tag``.
+
+        Returns:
+            The plaintext.
+
+        Raises:
+            CipherError: If the tag does not verify or the inputs are invalid.
+        """
+        ...
+
+
+class Aes256GcmSivCipher:
+    """AES-256-GCM-SIV, the crate's ``Aes256GcmSivCipher``.
+
+    Stateless: an instance holds no key and may be shared between threads.
+    """
+
+    @staticmethod
+    def _aead_for(key: bytes, nonce: bytes) -> AESGCMSIV:
+        """Check the key and nonce lengths, then build the primitive.
+
+        The key is checked first, as in the crate. ``cryptography`` would accept
+        a 16- or 24-byte key and silently run AES-128 or AES-192.
+
+        Raises:
+            CipherError: If the key is not 32 bytes, the nonce not 12, or the
+                OpenSSL backend has no AES-GCM-SIV (it needs OpenSSL 3.2+).
+        """
+        if len(key) != KEY_LEN:
+            raise CipherError(f"AES-256 key must be {KEY_LEN} bytes, got {len(key)}")
+        if len(nonce) != NONCE_LEN:
+            raise CipherError(f"nonce must be {NONCE_LEN} bytes, got {len(nonce)}")
+        try:
+            return AESGCMSIV(key)
+        except UnsupportedAlgorithm as exc:
+            raise CipherError(f"AES-256-GCM-SIV is unavailable: {exc}") from exc
+
+    def encrypt(self, key: bytes, nonce: bytes, aad: bytes, plaintext: bytes) -> bytes:
+        """Encrypt and authenticate ``plaintext`` under ``aad``.
+
+        Args:
+            key: The 32-byte AES-256 key.
+            nonce: The 12-byte nonce.
+            aad: Associated data, authenticated but not encrypted.
+            plaintext: The data to encrypt.
+
+        Returns:
+            ``ciphertext ‖ tag``, 16 bytes longer than ``plaintext``.
+
+        Raises:
+            CipherError: If the key is not 32 bytes or the nonce not 12.
+        """
+        return self._aead_for(key, nonce).encrypt(nonce, plaintext, aad)
+
+    def decrypt(self, key: bytes, nonce: bytes, aad: bytes, sealed: bytes) -> bytes:
+        """Verify and decrypt ``sealed`` (``ciphertext ‖ tag``).
+
+        Args:
+            key: The 32-byte AES-256 key.
+            nonce: The 12-byte nonce.
+            aad: The associated data the blob was sealed with.
+            sealed: ``ciphertext ‖ tag``.
+
+        Returns:
+            The plaintext.
+
+        Raises:
+            CipherError: If the key is not 32 bytes, the nonce not 12, or the
+                tag does not verify (wrong key, wrong AAD or tampered data; the
+                message does not say which).
+        """
+        aead = self._aead_for(key, nonce)
+        try:
+            return aead.decrypt(nonce, sealed, aad)
+        except InvalidTag as exc:
+            raise CipherError(_AUTH_FAILED) from exc

cryptovault/constants.py

@@ -0,0 +1,85 @@
+# Author: Julian Bolivar
+# Version: 0.2.0
+# Date: 2026-10-16
+"""Wire-format constants, with the values of the ``cryptovault`` crate 0.3.0.
+
+The blob size limits are derived exactly as the crate derives them. The crate
+sizes them for its concatenated FEC stack, and they apply unchanged to
+``NoFec`` blobs, so a blob is rejected on the same lengths in both languages.
+"""
+
+from typing import Final
+
+KEY_LEN: Final = 32
+"""AES-256 key length and master-key length, in bytes."""
+
+SALT_LEN: Final = 16
+"""Argon2id salt length, in bytes."""
+
+NONCE_LEN: Final = 12
+"""AES-256-GCM-SIV nonce length, in bytes."""
+
+TAG_LEN: Final = 16
+"""AEAD authentication tag length, in bytes."""
+
+HEADER_LEN: Final = 5
+"""Blob header length: ``version (1)`` + ``plaintext_len (u32 LE, 4)``."""
+
+BLOB_VERSION: Final = 1
+"""The only blob format version accepted."""
+
+MAX_PLAINTEXT_LEN: Final = 10 * 1024 * 1024
+"""Largest plaintext accepted in one blob (10 MiB)."""
+
+RECOMMENDED_MAX_PAYLOAD: Final = 128 * 1024
+"""Recommended largest plaintext per blob (128 KiB); frame larger data."""
+
+ARGON2_M_KIB: Final = 65536
+"""Argon2id memory cost, KiB (OWASP 2025: 64 MiB)."""
+
+ARGON2_T: Final = 3
+"""Argon2id time cost (iterations)."""
+
+ARGON2_P: Final = 4
+"""Argon2id parallelism (lanes)."""
+
+RS_DATA: Final = 223
+"""Reed-Solomon data bytes per codeword."""
+
+RS_PARITY: Final = 32
+"""Reed-Solomon parity bytes per codeword."""
+
+RS_BLOCK: Final = RS_DATA + RS_PARITY
+"""Reed-Solomon codeword length, in bytes (255)."""
+
+RS_INTERLEAVE_MAX: Final = 16
+"""Largest interleave depth: codewords per interleaver window."""
+
+VITERBI_CHUNK: Final = 490 * RS_BLOCK
+"""Reed-Solomon stream bytes per Viterbi sub-block (124 950)."""
+
+TERMINATION_OVERHEAD: Final = 2
+"""Bytes the Viterbi zero tail adds to each sub-block (``2L + 2``)."""
+
+
+def _max_blob_len() -> int:
+    """Derive the crate's ``MAX_BLOB_LEN``.
+
+    The largest protected payload is expanded by Reed-Solomon (``255/223``,
+    whole codewords), doubled by the Viterbi inner code, and given a two-byte
+    zero tail per Viterbi sub-block.
+
+    Returns:
+        The largest decoded blob length accepted, in bytes.
+    """
+    protected_max = MAX_PLAINTEXT_LEN + HEADER_LEN + NONCE_LEN + TAG_LEN
+    rs_max = -(-protected_max // RS_DATA) * RS_BLOCK
+    viterbi_chunks = -(-rs_max // VITERBI_CHUNK)
+    return rs_max * 2 + TERMINATION_OVERHEAD * viterbi_chunks
+
+
+MAX_BLOB_LEN: Final = _max_blob_len()
+"""Largest decoded blob accepted, in bytes (23 981 412)."""
+
+MAX_B64_LEN: Final = MAX_BLOB_LEN * 4 // 3 + 4
+"""Largest base64 input accepted, checked before decoding (31 975 220)."""

cryptovault/error.py

@@ -0,0 +1,76 @@
+# Author: Julian Bolivar
+# Version: 0.1.0
+# Date: 2026-10-16
+"""Typed error domain: one exception class per ``CryptoError`` variant.
+
+Every failure the package reports is a :class:`CryptoVaultError`. The subclass
+names the stage that failed, so a caller can tell a structural rejection from a
+failed authentication tag; the message stays generic and never repeats the
+caller's input. ``str(error)`` matches the ``Display`` output of the Rust crate
+for the same failure, prefix included.
+
+Example:
+    >>> from cryptovault.error import CipherError, CryptoVaultError
+    >>> error = CipherError("AES-256-GCM-SIV authentication failed")
+    >>> str(error)
+    'Cipher error: AES-256-GCM-SIV authentication failed'
+    >>> isinstance(error, CryptoVaultError)
+    True
+"""
+
+from typing import ClassVar
+
+
+class CryptoVaultError(Exception):
+    """Base of every error the package raises.
+
+    Subclasses set ``PREFIX``, the stage label the crate prints before the
+    message. Catch this class to handle every failure of the package at once.
+
+    Args:
+        message: The fixed, oracle-free description of the failure.
+
+    Attributes:
+        message: The description without the stage prefix.
+    """
+
+    PREFIX: ClassVar[str] = "CryptoVault error"
+
+    def __init__(self, message: str) -> None:
+        """Store the message and pass it to :class:`Exception`."""
+        super().__init__(message)
+        self.message = message
+
+    def __str__(self) -> str:
+        """Return ``"<PREFIX>: <message>"``, the crate's ``Display`` form."""
+        return f"{self.PREFIX}: {self.message}"
+
+
+class KeyDerivationError(CryptoVaultError):
+    """Argon2id or HKDF failure, or no entropy for a salt or DEK."""
+
+    PREFIX = "Key derivation error"
+
+
+class CipherError(CryptoVaultError):
+    """AEAD failure: a tag that does not verify, or no entropy for a nonce."""
+
+    PREFIX = "Cipher error"
+
+
+class ErrorCorrectionError(CryptoVaultError):
+    """Corruption beyond the capacity of a forward-error-correction codec."""
+
+    PREFIX = "Error correction error"
+
+
+class EncodingError(CryptoVaultError):
+    """Non-canonical base64, or text that is not valid UTF-8."""
+
+    PREFIX = "Encoding error"
+
+
+class InvalidInputError(CryptoVaultError):
+    """Structural or input-validation failure, raised before any decryption."""
+
+    PREFIX = "Invalid input"