Cryptography

This page describes the cryptography VaultTerm uses to keep secrets sealed at rest, to make the audit trail tamper-evident, and to bind a self-hosted instance to its licensed environment. It is the mechanical detail behind the Security model.

Envelope encryption

Secrets are protected with envelope encryption:

1. Each record gets its own data key (DEK).
2. The DEK encrypts the record’s contents.
3. The DEK is itself wrapped (encrypted) by a master key, and only the wrapped DEK is stored.

The bulk encryption uses AES-256-GCM, an authenticated cipher — so decryption also detects tampering with the ciphertext. Because every record has its own DEK and the DEKs are wrapped by the master key, no plaintext and no unwrapped key is stored beside the data.

Key providers

The master key is supplied by a pluggable key provider, selected with KEY_PROVIDER.

Provider	When to use	How the master key is held
local	Development and tests only	Read from DEV_MASTER_KEY. Not for production.
hcv-transit	Production	Master key sealed under a HashiCorp Vault Transit key; HSM / auto-unseal-backed. Unsealed only in memory at boot.

With hcv-transit, the master key never sits in plaintext on disk — VaultTerm holds the wrapped key and asks Vault Transit to unseal it into memory at startup. See Keys and licensing configuration for the full provider settings.

License-rooted audit chain

The audit trail is made tamper-evident with a checkpoint chain. Each checkpoint seals a contiguous range of audit rows with a hash, hash-links to the prior checkpoint, and is stamped with a monotonic license counter — rooting the chain in the deployment’s license so history cannot be silently rewritten. The full behavior, including offline verification, is described in Audit logs.

Post-quantum posture

VaultTerm uses crypto-agile, hybrid constructions so that today’s traffic and signatures stay safe against future quantum attacks:

• TLS key exchange uses a hybrid X25519MLKEM768 group — classical X25519 combined with the post-quantum ML-KEM-768. An attacker would have to break both to recover the session key, which protects against harvest-now-decrypt-later.
• License signatures are composite Ed25519 + ML-DSA-65 — both signatures must verify, so the license remains trustworthy even if one algorithm is later broken.
• AES-256 and SHA-256 are already considered quantum-resistant for VaultTerm’s purposes and are used as-is.

On-prem master-key binding

For self-hosted deployments, the master key’s unlock is derived from the environment it is licensed to run in — combining a host fingerprint, a hardware root, and the license signature. The instance can only unseal its key where all three line up, so a copied instance cannot simply be started on unlicensed hardware. This binding is part of the product-protection layer described in the Security model.

Related pages

• Keys and licensing configuration — provider and license settings.
• Audit logs — the checkpoint chain in operational detail.
• Security model — how these mechanisms fit the broker model.