Cryptography Internals

This document describes how quantabox-crypto protects data. For the user-facing workflow, see Post-Quantum Encryption.

Algorithm Suite #

The combined identifier reported by QuantaBox is ML-KEM-768+AES-256-GCM.

Key Hierarchy #

Disk sectors ──AES-256-GCM──> encrypted with the per-disk DEK
     DEK ──────ML-KEM-768───> wrapped (encapsulated) into a quantum-resistant blob
 wrapped DEK ──stored in────> the Key Vault (master-key-protected JSON)

1. DEK (Disk Encryption Key) -- a random 256-bit AES key, one per encrypted disk.
2. Wrapping -- the DEK is protected with ML-KEM-768: encapsulation yields a ciphertext plus a shared secret, and the DEK is encrypted under that shared secret with AES-256-GCM.
3. Storage -- wrapped keys are kept in the key vault, itself protected by a master key.

AES-256-GCM Layer #

The aes_gcm module provides:

• generate_key() -> [u8; 32] and generate_nonce() -> [u8; 12] (via OsRng).
• nonce_from_counter(counter) -> [u8; 12] -- a deterministic nonce derived from a sector index, enabling random-access sector encryption.
• encrypt(key, nonce, plaintext) / decrypt(key, nonce, ciphertext).
• sha3_256(data) -> [u8; 32].

ML-KEM-768 Layer #

The mlkem module provides:

• generate_keypair() -- an encapsulation (public) key and decapsulation (private) key.
• encapsulate(encap_key) -- produces (ciphertext, shared_secret).
• decapsulate(decap_key, ciphertext) -- recovers the 32-byte shared secret.
• wrap_disk_key(encap_key, dek) / unwrap_disk_key(decap_key, wrapped) -- wrap and recover a DEK using the KEM shared secret plus AES-256-GCM.

This is what makes the stored key material resistant to "harvest now, decrypt later" quantum attacks.

Sector-Based Disk Encryption #

The disk_encryption module encrypts disks one sector at a time:

• Plaintext sector size: 4096 bytes.
• Encrypted sector size: 4112 bytes (4096 + 16-byte GCM tag).
• Nonce: derived from the sector index (nonce_from_counter), so each sector has a unique nonce and any sector can be decrypted independently -- essential for random-access disk I/O.

On-Disk Encryption Header

Encrypted images carry a header describing the encryption:

The Key Vault #

The vault module is a JSON-backed key store:

• Structure: a version field and a map of key_id to VaultEntry.
• VaultEntry: key_id, the encrypted key bytes, a 12-byte nonce, an RFC 3339 created_at, and a human-readable label.
• Protection: entries are encrypted/decrypted with a master key supplied externally; the vault never stores the master key.
• Durability: saves are atomic (write to a temporary file, then rename).

API: KeyVault::new/load/save, store_key, retrieve_key, list_keys, remove_key.

Encrypted Backups and Exports #

The quantabox-backup crate reuses this crypto:

Backup (.qvbk)

1. Read the disk and compute its SHA3-256 checksum.
2. Compress with LZ4.
3. If a key is provided, prepend a random 12-byte nonce and encrypt the compressed data with AES-256-GCM.
4. Write data.qvbk plus a manifest.json recording the checksum, sizes, and timestamp.

Restore reverses these steps (decrypt, decompress, write), and the checksum verifies integrity.

Export package (QBOX_PKG)

A streaming format: an 8-byte QBOX_PKG magic, a version, the VM config JSON, then each disk written sector-by-sector. With encryption enabled, each sector is AES-256-GCM encrypted with a counter-derived nonce -- the same scheme as on-disk encryption -- so large disks stream without buffering the whole image. See Backup, Export and Import.

Summary #

QuantaBox combines a fast, quantum-resistant symmetric cipher (AES-256-GCM) with a post-quantum KEM (ML-KEM-768) to protect the keys, binds everything with SHA3-256 integrity checks, and stores wrapped keys in a master-key-protected vault. The same primitives secure disks at rest, encrypted backups, and encrypted export packages.