qsmm

Quantum-Secure Metadata Mesh — a research library exploring post-quantum encrypted storage primitives.

This is a research prototype, not a production library. It has not been externally audited. The cryptographic constructions are being studied — see SECURITY.md for what has been tested and what remains open.

What is this?

qsmm is a Rust library that replaces the traditional encrypted superblock with a distributed, deniable, quantum-resistant metadata system. Instead of a single locked map at a known offset, qsmm shatters metadata into threshold-recoverable shards, masks everything as random noise, and protects key material against quantum "harvest now, decrypt later" attacks.

Research question

Every encrypted filesystem has a superblock — a single block at a known offset that says "this is an encrypted volume." It's the one thing an adversary needs to find to prove you're hiding data.

Can we eliminate it? qsmm explores whether metadata can be shattered into pieces, scattered across a disk at unpredictable positions, and masked as noise — with no header, no magic bytes, no fixed offset.

This library provides the primitives for building deniable, quantum-resistant, and fault-tolerant storage systems. It is the cryptographic foundation behind darkfs.

Key Properties

• No superblock: Metadata is split into k-of-n shards via Shamir's Secret Sharing and scattered across the storage medium at cryptographically-derived positions. There is no header, no magic bytes, no fixed offset.
• Dark storage: The design goal is that every byte on disk is indistinguishable from /dev/urandom. Internal testing (chi-squared) shows no statistical bias, but this has not been externally verified.
• Multi-namespace deniability: Different keys reveal different "realities" on the same medium. Without the correct key, a namespace is not accessible and should not be detectable under single-snapshot analysis.
• Quantum-resistant: ML-KEM (FIPS 203) key encapsulation and ML-DSA (FIPS 204) signatures protect against future quantum computers.
• Resilient: Lose up to n - k shards and still reconstruct. No single point of failure.
• Memory safe: Written in Rust with #![deny(unsafe_code)]. All secrets are zeroized on drop.

Modules

Module	Codename	Purpose	Feature Flag
shield	The Shield	Post-quantum crypto (ML-KEM, ML-DSA, hybrid key wrapping)	shield
shatter	The Shatter	Distributed metadata mesh via Shamir's Secret Sharing	shatter
void	The Void	Entropy masking + multi-namespace plausible deniability	void
cloak	The Cloak	Fully homomorphic encryption for metadata operations	cloak (future)
proof	The Proof	Zero-knowledge integrity verification via zk-SNARKs	proof (future)

Quick Start

Add qsmm to your Cargo.toml:

[dependencies]
qsmm = "0.1"

Shard metadata across a medium (no superblock)

use qsmm::shatter::mesh::{MetadataMesh, MeshConfig};
use qsmm::types::{SecretKey, Threshold};

// Configure: need 3-of-5 shards to reconstruct.
let mesh = MetadataMesh::new(MeshConfig {
    threshold: Threshold::new(3, 5),
    total_blocks: 100_000,
});

let key = SecretKey::generate();
let hw_entropy = b"per-medium-random-seed";

// Shard metadata into 5 shares at deterministic positions.
let metadata = b"root-pointer:0xDEADBEEF;generation:42";
let placements = mesh.shard_metadata(metadata, &key, hw_entropy).unwrap();

// Write each placement.share to placement.target_block on the medium.
// ...

// Later: read back any 3+ shards to reconstruct.
let recovered = mesh.reconstruct_metadata(&retrieved_shards).unwrap();
assert_eq!(recovered, metadata);

Entropy masking (make data look like noise)

use qsmm::void::namespace::Namespace;
use qsmm::types::{BlockId, SecretKey};

let ns = Namespace::new(SecretKey::generate(), b"hw-entropy".to_vec()).unwrap();

// Seal: prepend ownership tag + XOR mask with CSPRNG stream.
let sealed = ns.seal_block(b"secret data", BlockId(42)).unwrap();
// sealed should be statistically indistinguishable from random noise.

// Open: unmask + verify ownership tag.
let data = ns.open_block(&sealed, BlockId(42)).unwrap();
assert_eq!(data.as_deref(), Some(b"secret data".as_slice()));

// Wrong key? Returns None — no error, no indication data exists.
let other = Namespace::new(SecretKey::generate(), b"hw-entropy".to_vec()).unwrap();
assert!(other.open_block(&sealed, BlockId(42)).unwrap().is_none());

Post-quantum key wrapping

use qsmm::shield::kem::{KemKeypair, KemLevel};
use qsmm::shield::wrap;
use qsmm::types::SecretKey;

// Generate a post-quantum keypair.
let keypair = KemKeypair::generate(KemLevel::Kem768);

// Wrap a symmetric key for safe storage/transmission.
let session_key = SecretKey::generate();
let wrapped = wrap::wrap_key(keypair.public_key(), &session_key).unwrap();

// Only the secret key holder can unwrap.
let recovered = wrap::unwrap_key(keypair.secret_key(), &wrapped).unwrap();
assert_eq!(recovered.as_bytes(), session_key.as_bytes());

Feature Flags

[features]
default = ["shield", "shatter", "void"]  # lightweight, all novel modules
shield  = [...]  # ML-KEM + ML-DSA post-quantum crypto
shatter = [...]  # Shamir secret sharing + deterministic shard placement
void    = [...]  # ChaCha20-based entropy masking + namespaces
# cloak = [...]  # FHE via TFHE-rs (future, heavy)
# proof = [...]  # zk-SNARKs via Halo2 (future, heavy)

Building

# Default features (shield + shatter + void)
cargo build

# All current features
cargo build --all-features

# Just the novel crypto (no PQ wrappers)
cargo build --features "shatter,void" --no-default-features

# Run tests
cargo test

# Generate docs
cargo doc --open

Architecture

See ARCHITECTURE.md for the full technical design, including the math behind each module and the integration model for existing encrypted filesystems.

Security

• All secret key material implements ZeroizeOnDrop — keys are securely erased from memory.
• Ownership tag verification uses constant-time comparison (subtle::ConstantTimeEq).
• Per-seal mask derivation prevents multi-snapshot XOR cancellation attacks.
• MiMC hash uses 91 rounds (meets standard recommendation for the 255-bit Pallas field).
• Shard collision resolution is deterministic — no timing leak from retry loops.
• Error messages are intentionally vague to avoid leaking cryptographic state.
• #![deny(unsafe_code)] is enforced at the crate root.

Documentation

• ARCHITECTURE.md — Module design, math, key derivation, integration model
• SECURITY.md — Threat model, audit findings, cryptographic analysis
• CONTRIBUTING.md — Development setup, code style, testing
• CHANGELOG.md — Release history

License

MPL-2.0