Encryption

Confidentiality in transit, at rest, and optionally end-to-end. Implements ADR-0014 (envelope encryption). The standout property: per-tenant keys enable crypto-shredding — instant, provable erasure by deleting a single key.

:::warning Key backup KMS key backup and recovery procedures must be tested on a schedule. Loss of a KEK means permanent, unrecoverable loss of the tenant’s encrypted data. There is no fallback. Test recovery before you need it. :::

1. Encryption in Transit

• TLS 1.3 for all external traffic; HSTS enforced; modern cipher policy; certificates via cert-manager + ACME (auto-rotated).
• mTLS between internal services for zero-trust service-to-service calls (enforced at deployment phase P4).
• Presigned direct-to-storage transfers ride the object store’s TLS endpoint. Presigned URLs are HTTPS-only — HTTP is not a valid scheme.
• Internal gRPC connections over mTLS carry a signed auth context so downstream services re-validate identity without re-querying the identity service.

2. Encryption at Rest — Key Hierarchy

flowchart TB
    classDef k fill:#fecaca,stroke:#b91c1c,color:#111827;
    classDef t fill:#fde68a,stroke:#b45309,color:#111827;
    classDef d fill:#bbf7d0,stroke:#15803d,color:#111827;
    root["Root KEK — in KMS / HSM (never exported)"]:::k
    root --> tkek["Per-tenant KEK (wrapped by root KEK)"]:::t
    tkek --> dek["Per-object DEK (random; wrapped by tenant KEK)"]:::d
    dek --> data["Encrypted chunks — AES-256-GCM"]:::d
    byok["BYOK / HYOK: tenant KEK = customer's own KMS key"]:::t -.-> tkek

• Envelope encryption (ADR-0014): a root KEK in the KMS/HSM (never leaves) wraps per-tenant KEKs, which wrap per-object DEKs.
• DEKs are ephemeral in memory during operations — they are never persisted in plaintext.
• KEKs never leave the KMS boundary — the KMS performs unwrap/wrap; BitVault only sees the result.
• Per-tenant keys = cryptographic isolation even within the shared-DB pool. A rogue DBA reading raw rows or backups sees only ciphertext they cannot decrypt.
• Kubernetes Secrets are encrypted via a KMS provider plugin. Backup snapshots are encrypted with separate, dedicated keys.

Supported KMS backends: HashiCorp Vault, AWS KMS, GCP Cloud KMS, Azure Key Vault.

3. Key Rotation

4. Crypto-Shredding (Erasure by Key Deletion)

Because each tenant has its own key, erasure = key deletion. Destroy the tenant KEK and all ciphertext — live data, replicas, and backups — becomes permanently unrecoverable, instantly. This is how BitVault implements:

• GDPR right-to-erasure without hunting every replica or backup copy.
• Tenant offboarding — data gone the moment the key is deleted, provably.
• BYOK kill-switch — a customer revokes their key and BitVault immediately loses access to their data, by design.

This turns “delete data everywhere” (hard, unverifiable) into “delete one key” (easy, provable). It is the highest-leverage security primitive in the design.

5. Customer-Managed Keys (BYOK / HYOK)

• BYOK (Bring Your Own Key): the tenant KEK lives in the customer’s KMS. They control rotation and revocation; revoking the key cuts BitVault’s access on demand.
• HYOK (Hold Your Own Key): the key never leaves the customer’s HSM. Unwrap operations are performed via the customer’s endpoint, introducing an availability coupling to that endpoint.

6. End-to-End Encryption (Opt-In)

The Private Vaults tier encrypts client-side. The server stores only ciphertext and cannot read the data. Sharing re-wraps the per-file key per recipient’s public key.

Tradeoff: E2E encryption disables server-side search, thumbnail previews, deduplication, and server-side Functions on that data — so it is opt-in, not the default.

7. Rogue DBA Mitigation

Per-tenant envelope encryption means a database administrator with direct SQL access or access to a backup snapshot sees only ciphertext. Without the tenant’s KEK (held in the KMS, not in the database), the data is unreadable. Combined with audit logging of all key operations and least-privilege DB access, this substantially reduces the insider threat surface.

8. Crypto Agility

Algorithm identifiers (e.g. blake3, aes-256-gcm) are stored per object, not per deployment. A hash or cipher migration is a lazy background re-encrypt operation, not a flag day. This future-proofs the design for a post-quantum algorithm transition.

Integrity hashing (BLAKE3, ADR-0016) and confidentiality encryption are distinct concerns; both apply to stored blobs.

9. Threats Addressed