Crate metamorphic_crypto 

metamorphic-crypto

Zero-knowledge end-to-end encryption core for the Metamorphic platform.

This library implements the cryptographic operations required by all Metamorphic clients (web/WASM, iOS/UniFFI, Android/UniFFI). It produces byte-compatible ciphertext with the existing JavaScript implementation so that data encrypted by one client can be decrypted by any other.

Security guarantees

• All secret key material is [Zeroize]-on-drop
• No unsafe code
• Constant-time comparisons via the underlying RustCrypto crates
• Randomness sourced directly from the OS CSPRNG (getrandom)

Ciphertext formats

The legacy Suite::Hybrid (default) formats are byte-for-byte unchanged. The opt-in CNSA 2.0 suites use an AES-256-GCM envelope keyed by HKDF-SHA512(info = suite_tag || context_label) (see suite); the nonce (12B) || ct || gcm_tag (16B) portion is the AEAD output.

Format	Layout
Secretbox	nonce (24B) || ciphertext (len + 16B MAC)
box_seal	ephemeral_pk (32B) || box ciphertext
Hybrid v1 (Cat-1)	0x01 || ML-KEM-512 ct (768B) || X25519 eph pk (32B) || nonce (24B) || secretbox ct
Hybrid v2 (Cat-3)	0x02 || ML-KEM-768 ct (1088B) || X25519 eph pk (32B) || nonce (24B) || secretbox ct
Hybrid v3 (Cat-5)	0x03 || ML-KEM-1024 ct (1568B) || X25519 eph pk (32B) || nonce (24B) || secretbox ct
PureCnsa2 (Cat-5)	0x10 || ML-KEM-1024 ct (1568B) || nonce (12B) || ct || gcm_tag (16B)
HybridMatched (Cat-3)	0x13 || ML-KEM-768 ct (1088B) || X448 eph pk (56B) || nonce (12B) || ct || gcm_tag (16B)
HybridMatched (Cat-5)	0x14 || ML-KEM-1024 ct (1568B) || P-521 eph pk (133B) || nonce (12B) || ct || gcm_tag (16B)

Signature formats

The default Suite::Hybrid is a composite ML-DSA + Ed25519 signature with strict-AND verification. The opt-in CNSA 2.0 suites place the fixed-size classical component first (so the variable ML-DSA tail needs no length prefix) and reuse the same I2OSP domain-separation framing. PureCnsa2 has no classical component. All are strict-AND verified.

Suite (level)	signature	public_key	secret_key
Hybrid (Cat-2/3/5)	tag || ed25519_sig (64B) || ml_dsa_sig	tag || ed25519_pk (32B) || ml_dsa_pk	tag || ed25519_seed (32B) || ml_dsa_seed (32B)
HybridMatched (Cat-3)	0x13 || ed448_sig (114B) || ml_dsa65_sig	0x13 || ed448_pk (57B) || ml_dsa65_pk	0x13 || ed448_seed (57B) || ml_dsa_seed (32B)
HybridMatched (Cat-5)	0x14 || ecdsa_p521_sig (132B) || ml_dsa87_sig	0x14 || p521_pk (133B) || ml_dsa87_pk	0x14 || p521_seed (66B) || ml_dsa_seed (32B)
PureCnsa2 (Cat-5)	0x10 || ml_dsa87_sig	0x10 || ml_dsa87_pk	0x10 || ml_dsa_seed (32B)

Separately, the ed25519 module exposes bare RFC 8032 Ed25519 (sign/verify, no framing, no PQ component). It exists only for byte-level interoperability with the deployed C2SP transparency-log witness ecosystem (Go sumdb/note, sigsum, transparency-dev, Tessera), which co-signs checkpoints with raw Ed25519. It is not a general-purpose signing API — use the hybrid PQ [sign] for Metamorphic authenticity.

Re-exports

pub use error::CryptoError;

pub use b64::parse_salt_from_key_hash;

pub use box_seal::box_seal;

pub use box_seal::box_seal_open;

pub use ed25519::ED25519_PUBLIC_KEY_LEN;

pub use ed25519::ED25519_SEED_LEN;

pub use ed25519::ED25519_SIGNATURE_LEN;

pub use ed25519::ed25519_generate_keypair;

pub use ed25519::ed25519_public_key;

pub use ed25519::ed25519_sign;

pub use ed25519::ed25519_verify;

pub use hash::sha3_256;

pub use hash::sha3_512;

pub use hash::sha3_512_with_context;

pub use hash::sha256;

pub use hash::sha512;

pub use hkdf::HASH_LEN as HKDF_SHA512_HASH_LEN;

pub use hkdf::hkdf_sha512;

pub use hybrid::HybridKeyPair;

pub use hybrid::SecurityLevel;

pub use hybrid::generate_hybrid_keypair;

pub use hybrid::generate_hybrid_keypair_512;

pub use hybrid::generate_hybrid_keypair_1024;

pub use hybrid::generate_hybrid_keypair_suite;

pub use hybrid::generate_hybrid_keypair_with_level;

pub use hybrid::hybrid_open;

pub use hybrid::hybrid_open_with_context;

pub use hybrid::hybrid_seal;

pub use hybrid::hybrid_seal_512;

pub use hybrid::hybrid_seal_1024;

pub use hybrid::hybrid_seal_suite;

pub use hybrid::hybrid_seal_suite_with_context;

pub use hybrid::hybrid_seal_with_level;

pub use hybrid::is_hybrid_ciphertext;

pub use kdf::derive_session_key;

pub use keys::KeyPair;

pub use keys::decrypt_private_key;

pub use keys::encrypt_private_key;

pub use keys::generate_key;

pub use keys::generate_keypair;

pub use keys::generate_salt;

pub use mac::HMAC_SHA256_LEN;

pub use mac::hmac_sha256;

pub use recovery::RecoveryKey;

pub use recovery::decrypt_private_key_with_recovery;

pub use recovery::encrypt_private_key_for_recovery;

pub use recovery::generate_recovery_key;

pub use recovery::recovery_key_to_secret;

pub use seal::seal_for_user;

pub use seal::seal_for_user_with_level;

pub use seal::seal_for_user_with_suite;

pub use seal::unseal_from_user;

pub use secretbox::decrypt_secretbox;

pub use secretbox::decrypt_secretbox_to_string;

pub use secretbox::encrypt_secretbox;

pub use secretbox::encrypt_secretbox_string;

pub use sign::HybridSignatureKeyPair;

pub use sign::SIGN_CONTEXT_V1;

pub use sign::SignatureLevel;

pub use sign::derive_public_key;

pub use sign::generate_signing_keypair;

pub use sign::generate_signing_keypair_44;

pub use sign::generate_signing_keypair_87;

pub use sign::generate_signing_keypair_suite;

pub use sign::generate_signing_keypair_with_level;

pub use sign::sign;

pub use sign::signature_posture;

pub use sign::signature_posture_from_signature;

pub use sign::verify;

pub use stack::RECOMMENDED_SIGNING_STACK_BYTES;

pub use stack::on_signing_stack;

pub use suite::SEAL_CONTEXT_V1;

pub use suite::Suite;

pub use vrf::ECVRF_EDWARDS25519_SHA512_TAI_SUITE;

pub use vrf::ECVRF_OUTPUT_LEN;

pub use vrf::ECVRF_PROOF_LEN;

pub use vrf::ECVRF_PUBLIC_KEY_LEN;

pub use vrf::ECVRF_SECRET_KEY_LEN;

pub use vrf::ecvrf_generate_keypair;

pub use vrf::ecvrf_proof_to_hash;

pub use vrf::ecvrf_prove;

pub use vrf::ecvrf_public_key;

pub use vrf::ecvrf_verify;

pub use vrf_p256::ECVRF_P256_OUTPUT_LEN;

pub use vrf_p256::ECVRF_P256_PROOF_LEN;

pub use vrf_p256::ECVRF_P256_PUBLIC_KEY_LEN;

pub use vrf_p256::ECVRF_P256_SECRET_KEY_LEN;

pub use vrf_p256::ECVRF_P256_SHA256_TAI_SUITE;

pub use vrf_p256::ecvrf_p256_generate_keypair;

pub use vrf_p256::ecvrf_p256_proof_to_hash;

pub use vrf_p256::ecvrf_p256_prove;

pub use vrf_p256::ecvrf_p256_public_key;

pub use vrf_p256::ecvrf_p256_verify;

Modules

b64

Base64 utilities (standard alphabet, with padding).

box_seal

X25519 sealed box (anonymous public-key encryption).

ed25519

Raw RFC 8032 Ed25519 — exposed strictly for transparency-log witness interoperability (C2SP signed-note / tlog-witness).

error

Error types for the crypto library.

hash

Cryptographic hash functions (SHA-3 and SHA-2 families).

hkdf

HKDF (HMAC-based Key Derivation Function, RFC 5869) — SHA-512.

hybrid

Hybrid post-quantum KEM: ML-KEM-512 + X25519 (Cat-1), ML-KEM-768 + X25519 (Cat-3, default), and ML-KEM-1024 + X25519 (Cat-5).

kdf

Argon2id key derivation.

keys

Key generation and private-key encrypt/decrypt helpers.

mac

Message authentication codes (HMAC).

recovery

Recovery key generation and encoding.

seal

Unified seal/unseal that auto-detects hybrid (v2/v3) vs legacy (v1) format.

secretbox

XSalsa20-Poly1305 authenticated encryption (NaCl secretbox).

sign

Hybrid post-quantum signatures: ML-DSA (FIPS 204) + Ed25519 composite.

stack

Large-stack execution guard for lattice signing/keygen.

suite

CNSA 2.0 suite axis — shared scaffolding for the post-quantum suites added in v0.7.0 (additive, non-breaking).

vrf

Verifiable Random Function (VRF) — ECVRF-EDWARDS25519-SHA512-TAI (RFC 9381).

vrf_p256

Verifiable Random Function (VRF) — ECVRF-P256-SHA256-TAI (RFC 9381).