CryptoVault-Python

A Python implementation of the cryptovault blob format, byte-compatible with the Rust crate. AES-256-GCM-SIV under an HKDF-SHA256 key, Argon2id key derivation and DEK/KEK key wrapping, followed by the crate's forward-error correction: Reed-Solomon, an interleaver and a Viterbi code, or no FEC at all.

Status: 0.2.0, alpha. Every FEC strategy of cryptovault 0.3.0 is implemented and checked in both directions against the crate.

What it does

Two services that share a 32-byte key can encrypt and authenticate messages for each other. A blob made on either side opens on the other, Rust → Python and Python → Rust. The package opens no connections and knows nothing about transports: it turns text or key material into a blob and back, and the caller moves the blob.

The Rust crate stacks two independent layers: an AEAD that provides all of the security, then an FEC that adds channel resilience and no security. Both are implemented here, with the same four FEC strategies as the crate.

Installation

pip install cryptovault-py

The import name is cryptovault. Requirements lists the supported Python versions and the cryptography and OpenSSL floor.

Quick start

>>> from cryptovault import CryptoVault, generate_dek, generate_salt
>>> vault = CryptoVault.default()             # Argon2id + AES-256-GCM-SIV + concatenated FEC

>>> key = generate_dek()                      # or vault.derive_key(password, salt)
>>> blob = vault.encrypt_with_key(key, "sk-secret")
>>> vault.decrypt_with_key(key, blob)
'sk-secret'

>>> salt = generate_salt()                    # one per context, kept by the caller
>>> kek = generate_dek()
>>> dek = generate_dek()
>>> wrapped = vault.wrap_key(kek, salt, dek)  # the salt is bound as AAD
>>> vault.unwrap_key(kek, salt, wrapped) == dek
True

CryptoVault.default() matches CryptoVault::default() in Rust. To pick another FEC strategy, compose the vault yourself; the constructor has no defaults:

>>> from cryptovault import Aes256GcmSivCipher, Argon2Kdf, NoFec
>>> aead_only = CryptoVault(Argon2Kdf(), Aes256GcmSivCipher(), NoFec())
>>> aead_only.decrypt_with_key(key, aead_only.encrypt_with_key(key, "hi"))
'hi'

derive_key(password, salt) runs Argon2id with the crate's OWASP-2025 profile (64 MiB, three passes, four lanes). Call it once per session and keep the key.

Blob layout

blob    = base64( fec.encode( header ‖ nonce(12 B) ‖ ciphertext ‖ tag(16 B) ) )   standard, padded
header  = version (0x01) ‖ plaintext_len (u32, little-endian)
key     = HKDF-SHA256( salt = none, ikm = 32-byte master key, info = "cryptovault:v1:aead", L = 32 )
AAD     = purpose ‖ header ‖ aad_extra
purpose = 0x01 data · 0x02 wrapped key
extra   = empty for data · the salt for a wrapped key (authenticated, never stored)
cipher  = AES-256-GCM-SIV, fresh random 12-byte nonce per message

The header is bound as associated data, so changing any bit of it fails authentication. The purpose byte keeps a data blob from opening as a wrapped key, and the other way round. As for the version byte, it leaves room for the format to evolve; today only 0x01 is accepted.

FEC strategies

The FEC layer sits after the AEAD and only helps a blob survive a noisy channel. Correction is all or nothing. Within capacity the blob comes back exact; past it, decryption fails with a typed error and never returns wrong plaintext, because the AEAD tag checks the result.

The CSPRNG variant derives its seed from the master key with HKDF (info = "cryptovault:v1:interleaver"), and both ends must build it from the same master and depth. It is obfuscation, not security.

The codecs are pure Python, so they are much slower than the Rust crate. Measured with CPython 3.11 on Windows:

A clean Viterbi sub-block decodes directly. One with channel errors runs the full trellis, which in Python costs about 12 µs per coded bit pair, or about 12 s for a full 124 950-byte sub-block. Noisy channels carrying large messages pay that price.

Security model

All cryptographic primitives come from the cryptography package. Nothing here is home-rolled crypto.

Out of scope (what it does NOT defend against)

• Weak passwords. Argon2id slows guessing down; it does not make a weak password strong.
• Replay. A valid blob stays valid. Detecting repeats is the caller's protocol concern.
• Traffic analysis. The header carries the plaintext length in the clear, and the blob size follows from it.
• Channel errors past the FEC capacity. The blob fails closed and never decrypts to something wrong. With NoFec, a single flipped bit is enough.
• Memory disclosure. The crate wipes secrets from memory; Python's immutable str and bytes cannot promise that, and this package does not try.
• Host compromise. A key in process memory is as safe as the process.

Operational contracts (the caller must honor)

• Use exactly 32 bytes of key. A shorter or longer key is an error, not something the package pads or truncates.
• Use a fresh salt per context, from generate_salt(). The same password and salt give the same key.
• Rate-limit derive_key for untrusted callers. Each call costs 64 MiB and noticeable CPU.
• Rekey before ~2⁴⁸ messages per key. That is the birthday bound for random 96-bit nonces.
• Decode with the same FEC strategy you encoded with. A blob from a default Rust vault opens with CryptoVault.default(); one from a NoFec vault needs a NoFec vault here.
• Bound decrypt input from untrusted sources. with_max_blob_len(cap) returns a vault that rejects larger blobs before any decryption work. With FEC this also bounds the decode time, which grows with the number of corrupted Viterbi sub-blocks.
• One blob, one message. Framing and delivery belong to the caller.

Errors

Every failure is a CryptoVaultError. The subclass names the stage that failed, and str() matches the crate's Display for the same input, word for word:

Compatibility testing

The test suite replays reference data that the crate itself produced. For NoFec: its constants, data blobs up to 128 KiB, wrapped keys, Argon2id outputs, and the exact error for 358 adversarial inputs (every single-bit flip of a blob, truncations, bad versions and lengths, non-canonical base64, wrong keys and salts, invalid UTF-8). For the FEC layer: the Reed-Solomon codewords and the outcome of 146 corrupted decodes, the interleaver permutations (the CSPRNG layer included), Viterbi encodings and 26 corrupted decodes down to the wrong bytes a heavily damaged stream decodes to, and 335 adversarial blobs under three strategies (sampled bit flips, bursts, truncation, rewritten headers, wrong keys and salts). In the other direction, a second test hands the crate blobs made in Python under every strategy and checks that it opens each one. The generator lives in interop/rust:

uv run pytest                     # full suite, Rust fixtures included
uv run pytest -m interop          # Python → Rust; needs the Rust toolchain
cargo run --release --manifest-path interop/rust/Cargo.toml -- fixtures \
    > tests/fixtures/rust_nofec.json   # regenerate the NoFec fixtures
cargo run --release --manifest-path interop/rust/Cargo.toml -- fec-fixtures \
    > tests/fixtures/rust_fec.json     # regenerate the FEC fixtures

Requirements

• Python 3.11 or newer. Tested on Linux and Windows with 3.11 and 3.14.
• cryptography 45.0.1 or newer, linked against OpenSSL 3.2 or newer (AES-GCM-SIV and Argon2id need it; the CSPRNG layer also uses its ChaCha20). Releases before 45.0.1 reject an empty plaintext, which the crate allows. The official wheels qualify.

Development

uv sync --locked
uv run ruff check . && uv run ruff format --check . && uv run mypy . && uv run pytest
uv run pip-audit
uv build

Roadmap

1. NoFec blob format, Argon2id and key wrapping. Implemented and cross-checked against the crate in both directions.
2. The FEC strategies. Reed-Solomon, the interleaver and Viterbi, so any cryptovault blob can be read from Python. Implemented and cross-checked in both directions.
3. A compiled FEC accelerator. The codecs are pure Python, and a damaged sub-block runs the full Viterbi trellis at about 12 µs per stage: a 128 KiB blob with one flipped bit takes about 15 s to decrypt. The plan is an optional Rust extension (PyO3) that wraps the same reedsolomon and viterbi crates the reference crate uses, with the pure-Python codecs kept as the fallback where no wheel exists. The crate fixtures stay as its parity check.

License

Licensed under either of

• MIT license (LICENSE-MIT), or
• Apache License, Version 2.0 (LICENSE-APACHE)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this package by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.

Copyright © 2026 Julian Bolivar / BolivarTech.