metamorphic-crypto 0.7.1

Zero-knowledge end-to-end encryption with post-quantum hybrid KEM (ML-KEM + X25519) and an opt-in CNSA 2.0 suite axis (matched-strength hybrid + pure ML-KEM-1024 / ML-DSA-87 / AES-256-GCM)
Documentation

metamorphic-crypto

Zero-knowledge end-to-end encryption library with post-quantum hybrid KEM, hybrid PQ signatures, and an opt-in CNSA 2.0 suite axis (matched-strength hybrid + pure ML-KEM-1024 / ML-DSA-87 / AES-256-GCM).

Built for Metamorphic and Mosslet — privacy-first apps by Moss Piglet Corporation where all user data is encrypted client-side and the server only stores opaque ciphertext.

What this provides

  • Secretbox (XSalsa20-Poly1305) — symmetric authenticated encryption
  • Sealed box (X25519) — anonymous public-key encryption (libsodium-compatible)
  • Hybrid PQ KEM (ML-KEM-512 + X25519) — NIST Cat-1 post-quantum key encapsulation (opt-in)
  • Hybrid PQ KEM (ML-KEM-768 + X25519) — NIST Cat-3 post-quantum key encapsulation (default)
  • Hybrid PQ KEM (ML-KEM-1024 + X25519) — NIST Cat-5 post-quantum key encapsulation (opt-in)
  • Argon2id KDF — password-based key derivation (libsodium INTERACTIVE parameters)
  • Hybrid PQ signatures (ML-DSA + Ed25519) — NIST Cat-2/3/5 composite digital signatures (strict AND)
  • CNSA 2.0 suite axis (opt-in) — matched-strength hybrid (X448 / P-521 / Ed448 / ECDSA-P-521) and pure post-quantum (ML-KEM-1024, ML-DSA-87, AES-256-GCM)
  • Hashing (SHA3-512/256, SHA-256/512) — public, one-shot digest functions (e.g. for key fingerprints / safety numbers)
  • WASM bindings — browser-ready via wasm-pack
  • Recovery keys — human-readable base32 encoding for key backup

Security levels

Level ML-KEM NIST Category Equivalent Version Tag Default
Cat-1 512 1 ~AES-128 0x01 No
Cat-3 768 3 ~AES-192 0x02 Yes
Cat-5 1024 5 ~AES-256 0x03 No

NIST (FIPS 203) standardizes ML-KEM only at categories 1/3/5 — there is no category-2/4 parameter set, so none is offered. All levels use the same combiner construction. The classical half is X25519 (~Cat-1 classical) at every tier — it does not scale up with the ML-KEM parameter set; at Cat-3/Cat-5 the post-quantum half dominates and X25519 is the classical floor (standard hybrid-KEM practice: a break requires defeating both halves). hybrid_open auto-detects the level from the version tag byte — old and new ciphertext coexist seamlessly.

Security properties

  • #![forbid(unsafe_code)] — no unsafe anywhere in the crate
  • All secret key material zeroized after use
  • Constant-time MAC comparison via RustCrypto
  • OS CSPRNG via getrandom (no userspace PRNG)
  • Hybrid construction: both ML-KEM AND X25519 must be broken to compromise a sealed key

Hybrid KEM construction

The hybrid combiner matches the format used by @noble/post-quantum's ml_kem768_x25519:

Seed expansion:  SHAKE256(seed_32) → 96 bytes [ML-KEM seed (64) || X25519 sk (32)]
Combiner:        SHA3-256(ss_mlkem || ss_x25519 || ct_x25519 || pk_x25519 || label)

Cat-1 (ML-KEM-512, opt-in)

Public key:   ML-KEM-512 ek (800 B) || X25519 pk (32 B) = 832 bytes
Ciphertext:   0x01 || ML-KEM-512 ct (768 B) || X25519 eph pk (32 B) || nonce (24 B) || secretbox ct

Cat-3 (ML-KEM-768, default)

Public key:   ML-KEM-768 ek (1184 B) || X25519 pk (32 B) = 1216 bytes
Ciphertext:   0x02 || ML-KEM-768 ct (1088 B) || X25519 eph pk (32 B) || nonce (24 B) || secretbox ct

Cat-5 (ML-KEM-1024, opt-in)

Public key:   ML-KEM-1024 ek (1568 B) || X25519 pk (32 B) = 1600 bytes
Ciphertext:   0x03 || ML-KEM-1024 ct (1568 B) || X25519 eph pk (32 B) || nonce (24 B) || secretbox ct

Targets

Target Build Use case
Native cargo build Tests, CLI tools, Elixir NIF (metamorphic_crypto Hex package)
WASM wasm-pack build --target web Browser (Phoenix LiveView, any SPA)
iOS UniFFI (planned) Native Swift apps
Android UniFFI (planned) Native Kotlin apps

Usage

use metamorphic_crypto::{generate_key, encrypt_secretbox_string, decrypt_secretbox_to_string};
use metamorphic_crypto::{generate_hybrid_keypair, hybrid_seal, hybrid_open};
use metamorphic_crypto::{generate_hybrid_keypair_512, hybrid_seal_512};
use metamorphic_crypto::{generate_hybrid_keypair_1024, hybrid_seal_1024};

// Symmetric encryption
let key = generate_key();
let ciphertext = encrypt_secretbox_string("sensitive data", &key).unwrap();
let plaintext = decrypt_secretbox_to_string(&ciphertext, &key).unwrap();
assert_eq!(plaintext, "sensitive data");

// Hybrid PQ seal (Cat-3, default)
let kp = generate_hybrid_keypair();
let sealed = hybrid_seal(b"context_key_bytes", &kp.public_key).unwrap();
let opened = hybrid_open(&sealed, &kp.secret_key).unwrap();

// Hybrid PQ seal (Cat-5)
let kp5 = generate_hybrid_keypair_1024();
let sealed5 = hybrid_seal_1024(b"context_key_bytes", &kp5.public_key).unwrap();
let opened5 = hybrid_open(&sealed5, &kp5.secret_key).unwrap(); // auto-detects level

// Hybrid PQ seal (Cat-1)
let kp1 = generate_hybrid_keypair_512();
let sealed1 = hybrid_seal_512(b"context_key_bytes", &kp1.public_key).unwrap();
let opened1 = hybrid_open(&sealed1, &kp1.secret_key).unwrap(); // auto-detects level

Hashing

Public, one-shot digest functions over the already-present, audited sha3 and sha2 dependencies. These are intended for public data only — key fingerprints / safety numbers and key-transparency-log entries — where both the input (e.g. a public key) and the output digest are meant to be public.

sha3_512 is the recommended default (NIST Cat-5, ~256-bit collision resistance, consistent with the crate's Keccak-based combiner). sha3_256, sha256, and sha512 are provided so integrators can match an existing format.

use metamorphic_crypto::{sha3_512, sha3_256, sha256, sha512};

// Take raw bytes, return fixed-size byte arrays.
let digest: [u8; 64] = sha3_512(b"public key bytes"); // recommended default
let d256:   [u8; 32] = sha3_256(b"...");
let s256:   [u8; 32] = sha256(b"...");   // SHA-2 interop
let s512:   [u8; 64] = sha512(b"...");   // SHA-2 interop

// Encode the digest yourself when needed:
use metamorphic_crypto::b64;
let fingerprint_b64 = b64::encode(&digest);

Domain separation (recommended for fingerprints / transparency logs)

For key fingerprints, safety numbers, and key-transparency-log entries, prefer sha3_512_with_context, which binds the digest to a versioned context label so the same bytes hashed for different purposes can never collide or be reinterpreted across contexts. It is exactly as strong as sha3_512 — it is SHA3-512, over an unambiguously framed message — and makes intent explicit:

use metamorphic_crypto::sha3_512_with_context;

let fp  = sha3_512_with_context("mosslet/key-fingerprint/v1", pubkey_bytes);
let log = sha3_512_with_context("mosslet/log-entry/v1", entry_bytes);
// fp and log are unrelated even if the byte inputs coincide.

Stable wire format (reproduce exactly for cross-language parity):

SHA3-512( u64_be(len(context_utf8)) || context_utf8 || data )

The 8-byte big-endian length prefix makes the (context, data) boundary unambiguous (no boundary-confusion collisions). Use a versioned namespace label.

Encoding: the native functions take &[u8] and return raw byte arrays — encode to base64 or hex at the call site. The WASM bindings take/return base64 to match the rest of the WASM API (see below).

Do not hash secrets with these. A bare hash makes no guarantees about its inputs, and (consistent with the rest of the crate) the hashing path adds no zeroize/constant-time ceremony — wiping a transient copy of already-public data would add cost without protection. If you need to process secret material (passwords, private keys), use the right construction instead — this crate's Argon2id derive_session_key for password-based derivation, or a dedicated KDF/MAC. The encryption APIs that handle secrets already zeroize on drop.

Hybrid PQ signatures

Composite digital signatures: every message is signed by both ML-DSA (FIPS 204) and Ed25519 (RFC 8032), and verification requires both to be valid (strict AND). An attacker has to break both a lattice scheme and an elliptic-curve scheme to forge, and cannot strip one algorithm to downgrade the other. This is the signing counterpart to the hybrid KEM above.

use metamorphic_crypto::{generate_signing_keypair, sign, verify, SIGN_CONTEXT_V1};

let kp = generate_signing_keypair(); // Cat-3 (ML-DSA-65 + Ed25519), default
let sig = sign(b"transparency log entry", SIGN_CONTEXT_V1, &kp.secret_key).unwrap();
assert!(verify(b"transparency log entry", SIGN_CONTEXT_V1, &sig, &kp.public_key).unwrap());

// Re-derive the public key from a backed-up secret key:
use metamorphic_crypto::derive_public_key;
assert_eq!(derive_public_key(&kp.secret_key).unwrap(), kp.public_key);

Cat-2 (generate_signing_keypair_44) and Cat-5 (generate_signing_keypair_87) are also available; verify auto-detects the level from the signature's version tag. The secret_key field is zeroized on drop.

Signing levels and mode

Level ML-DSA NIST Category Equivalent Version Tag Default
Cat-2 ML-DSA-44 2 ~AES-128 0x01 No
Cat-3 ML-DSA-65 3 ~AES-192 0x02 Yes
Cat-5 ML-DSA-87 5 ~AES-256 0x03 No

ML-DSA is signed with the hedged (randomized) variant — FIPS 204's default and most conservative mode (resilient to RNG failure, hardened against fault / side-channel attacks that deterministic lattice signing invites). Ed25519 is deterministic per RFC 8032. As a result signature bytes are non-reproducible, but the wire format is deterministic and pinned.

Domain separation and wire format

Both algorithms sign the same domain-separated message, framed exactly like sha3_512_with_context (a length-prefixed context):

signed_msg = I2OSP(len(context_utf8), 8) || context_utf8 || message

ML-DSA signs signed_msg with an empty native context, so the framing is identical for both algorithms and across every language binding. Byte layout (Ed25519 first, fixed-size, so the ML-DSA tail needs no length prefix):

signature  = tag || ed25519_sig (64 B) || ml_dsa_sig (2420 / 3309 / 4627 B)
public_key = tag || ed25519_pk  (32 B) || ml_dsa_pk  (1312 / 1952 / 2592 B)
secret_key = tag || ed25519_seed(32 B) || ml_dsa_seed(32 B)              = 65 B

Dependency audit posture

Dependency Version Audited Notes
ed25519-dalek 2.x Yes (mature) Widely deployed RFC 8032 implementation.
ml-dsa 0.1.x No (RustCrypto) FIPS 204 (final). New crate, not yet independently audited. Pinned; tracked for the FIPS-mode roadmap.

ML-DSA is defense-in-depth on top of the independently-strong Ed25519: even if a flaw were found in the young ml-dsa implementation, the composite remains at least as strong as Ed25519. This is stated honestly so integrators can choose while the post-quantum implementation matures toward audit / FIPS validation.

CNSA 2.0 suite axis (opt-in)

By default everything above is Suite::Hybrid — the classical+PQ strict-AND constructions (ML-KEM + X25519; ML-DSA + Ed25519). If you have no specific mandate, that is the recommended choice and you can ignore this section.

For deployments that must follow the NSA's Commercial National Security Algorithm Suite 2.0 (CNSA 2.0 / NIST IR 8547), a Suite axis lets you raise the posture with a single extra argument. It is orthogonal to the SecurityLevel (Cat-1/3/5) you already know, so you really have two independent knobs:

            posture (Suite)                  ×   parameter set (SecurityLevel)
  ┌──────────────────────────────┐               ┌───────────────────────┐
  │ Hybrid         (default)      │               │ Cat-1 / Cat-3 / Cat-5 │
  │ HybridMatched  (opt-in)       │               └───────────────────────┘
  │ PureCnsa2      (opt-in)       │
  └──────────────────────────────┘
Suite What it is Classical partner Status
Hybrid Existing strict-AND classical+PQ. Byte-for-byte unchanged. X25519 / Ed25519 (every tier) Default, recommended
HybridMatched Classical partner matched to the PQ category so it is never the weak link KEM: Cat-3→X448, Cat-5→P-521 ECDH · Sign: Cat-3→Ed448, Cat-5→ECDSA-P-521 Opt-in
PureCnsa2 Pure post-quantum, no classical half (the CNSA-2.0 box) none Opt-in, Cat-5 only

HybridMatched at the lowest rung (KEM Cat-1 / sign Cat-2) is identical to Hybrid — no new format is produced there, so nothing breaks.

New wire formats (new suites only)

The Hybrid suite (and HybridMatched at the lowest rung) keep their existing 0x01/0x02/0x03 ciphertext tags and byte layout untouched. The matched / pure suites use new tags and a CNSA-correct seal envelope:

Suite + level KEM Tag
PureCnsa2 Cat-5 ML-KEM-1024 + AES-256-GCM 0x10
HybridMatched Cat-3 ML-KEM-768 + X448 + AES-256-GCM 0x13
HybridMatched Cat-5 ML-KEM-1024 + P-521 ECDH + AES-256-GCM 0x14 
ikm  = ss_mlkem (PureCnsa2)  |  ss_mlkem || ss_ecc (HybridMatched)
key  = HKDF-SHA512(ikm, info = suite_tag || context_label)   -> 32-byte AES-256 key
out  = AES-256-GCM(key, 96-bit random nonce, AAD = suite_tag || context_label)
wire = tag(1) || kem_ct || [ecc_eph_pk] || nonce(12) || ct || gcm_tag(16)

Each encapsulation yields a fresh KEM secret, so the derived AES-256 key is single-use and the random 96-bit nonce can never repeat — SIV-grade misuse resistance without leaving the CNSA-approved set (no AES-GCM-SIV). Note the deliberate hash split: HKDF-SHA512 for key derivation here; SHA3-512 stays the choice for leaf/transcript hashing (sha3_512_with_context).

Context labels

The new suites bind a versioned context label into both the HKDF info and the GCM AAD (and, for signatures, the I2OSP-framed message). Grammar: "<namespace>/<purpose>/v<major>". The namespace is the one per-tenant knob; the protocol shape stays fixed. Library defaults are SEAL_CONTEXT_V1 ("metamorphic/seal/v1") and SIGN_CONTEXT_V1 ("metamorphic/sign/v1"); pass your own (e.g. "mosslet/seal/v1") to namespace your deployment.

Usage (Rust)

use metamorphic_crypto::{
    Suite, SecurityLevel, SignatureLevel, SEAL_CONTEXT_V1, SIGN_CONTEXT_V1,
    generate_hybrid_keypair_suite, hybrid_seal_suite, hybrid_open_with_context,
    generate_signing_keypair_suite, sign, verify,
};

// --- KEM / seal: the pure CNSA-2.0 box (ML-KEM-1024 + AES-256-GCM) ---
let kp = generate_hybrid_keypair_suite(Suite::PureCnsa2, SecurityLevel::Cat5).unwrap();
let sealed = hybrid_seal_suite(b"context_key_bytes", &kp.public_key,
                               Suite::PureCnsa2, SecurityLevel::Cat5).unwrap();
// `hybrid_open` auto-detects the tag using the DEFAULT context label; if you
// sealed with a custom label, open with it explicitly:
let opened = hybrid_open_with_context(&sealed, &kp.secret_key, SEAL_CONTEXT_V1).unwrap();

// --- Signatures: ML-DSA-87 only (Cat-5 pure) ---
let sk = generate_signing_keypair_suite(Suite::PureCnsa2, SignatureLevel::Cat5).unwrap();
let sig = sign(b"checkpoint", SIGN_CONTEXT_V1, &sk.secret_key).unwrap();
assert!(verify(b"checkpoint", SIGN_CONTEXT_V1, &sig, &sk.public_key).unwrap());
// `sign` / `verify` / `derive_public_key` auto-detect the suite from the version
// tag — no suite argument is needed once the key exists.

seal_for_user_with_suite is the user-facing seal that falls back to legacy X25519 when no PQ key is present, mirroring seal_for_user_with_level.

Honest claims

Claim: "CNSA 2.0 algorithm suite, NCC-audited components, pure-Rust, memory-safe (forbid-unsafe)." Not "FIPS 140-3 validated." PureCnsa2 is more standards-compliant but leans entirely on the (not-yet-independently-audited at our layer) lattice implementation, which is exactly why the strict-AND Hybrid default stays recommended: it keeps the classical backstop until the PQ implementations are audited / validated.

WASM (browser)

wasm-pack build --target web --release

import init, { deriveSessionKey, encryptSecretboxString } from './pkg/metamorphic_crypto.js';

await init('/path/to/metamorphic_crypto_bg.wasm');

const key = deriveSessionKey(password, saltBase64);
const ciphertext = encryptSecretboxString("hello", key);

Hashing (WASM)

Digest exports take base64-encoded input and return the digest as base64. Decode or re-encode to hex on the JS side if a hex fingerprint is required.

import init, { sha3_512, sha3_512WithContext } from './pkg/metamorphic_crypto.js';
await init();

const dataB64 = btoa("public key bytes");
const digestB64 = sha3_512(dataB64); // also: sha3_256, sha256, sha512

// Domain-separated (recommended for fingerprints / transparency logs):
const fp = sha3_512WithContext("mosslet/key-fingerprint/v1", dataB64);

Signatures (WASM)

Keys and signatures are base64; the message is base64 and context is a UTF-8 string. verify returns true only if both component signatures are valid.

import init, { generateSigningKeyPair, sign, verify } from './pkg/metamorphic_crypto.js';
await init();

const kp = generateSigningKeyPair("cat3"); // { publicKey, secretKey }
const msg = btoa("transparency log entry");
const sig = sign(msg, "metamorphic/sign/v1", kp.secretKey);
const ok = verify(msg, "metamorphic/sign/v1", sig, kp.publicKey); // true

CNSA 2.0 suites (WASM)

The Suite axis is exposed as a string argument ("hybrid" (default), "hybridMatched", or "pureCnsa2") alongside the usual "cat1"/"cat3"/"cat5" level. Decryption / verification auto-detect the suite from the version tag.

import init, {
  generateHybridKeyPairSuite, hybridSealSuite, hybridOpenWithContext,
  generateSigningKeyPairSuite, sign, verify,
} from './pkg/metamorphic_crypto.js';
await init();

// Pure CNSA-2.0 KEM box (ML-KEM-1024 + AES-256-GCM)
const kp = generateHybridKeyPairSuite("pureCnsa2", "cat5"); // { publicKey, secretKey }
const sealed = hybridSealSuite(btoa("key material"), kp.publicKey, "pureCnsa2", "cat5");
// Open with the context label used at seal time (default "metamorphic/seal/v1"):
const opened = hybridOpenWithContext(sealed, kp.secretKey, "metamorphic/seal/v1"); // base64

// Pure ML-DSA-87 signatures
const sk = generateSigningKeyPairSuite("pureCnsa2", "cat5");
const sig = sign(btoa("checkpoint"), "metamorphic/sign/v1", sk.secretKey);
const ok = verify(btoa("checkpoint"), "metamorphic/sign/v1", sig, sk.publicKey); // true

For a custom per-tenant namespace, use hybridSealSuiteWithContext(..., "mosslet/seal/v1") and open with the same label. sealForUserWithSuite mirrors sealForUser with the suite/level appended.

Tests

cargo test          # unit + integration + cross-level compatibility
cargo clippy        # zero warnings
cargo fmt --check   # formatted

License

Dual-licensed under MIT or Apache-2.0 at your option.