Customer-Managed Keys (BYOK)

BYOK replaces BYOVault's shared, derived key with a genuinely random key generated per file and wrapped by a key you hold, in your own AWS KMS or Azure Key Vault.

The envelope-encryption model

On the default path, every tenant’s encryption key is derived from one shared master key via HKDF (see Key Derivation & Hierarchy). BYOK does not change where that derivation pulls from — it replaces the derivation itself.

For a tenant with an active BYOK configuration, each file gets its own File Key: a genuinely random 32-byte (256-bit) AES key, generated fresh per file and never reused across files or derived from any shared secret.

That File Key encrypts the file’s content exactly the way the default path already does — the same AES-256-GCM mechanics, the same per-chunk IV discipline, described in Encryption. Nothing about how content is encrypted changes under BYOK; only how the key protecting that content comes into existence changes.

Wrapping and key lifetime

Once a file’s chunks are encrypted, the File Key itself is wrapped — encrypted — exactly once by the tenant’s own KMS key, and the wrapped result is what gets persisted alongside that file’s catalog record.
The plaintext File Key is held in memory only for the duration of that one upload or restore operation and is wiped immediately afterward.
Wrapping happens once per file, never once per chunk, because a per-chunk call pattern would multiply request volume against the customer’s own KMS quotas far beyond what either provider’s request-rate limits comfortably sustain at backup scale.

Not a different key source — a different mechanism

This is a structurally different path from the default one, not simply the same derivation pointed at a different secret. The default path always computes a tenant’s key mathematically from a shared master key. BYOK never does this: the File Key is generated by a cryptographically random source, has no relationship to any other file’s key or to any shared master key, and is recoverable only by unwrapping it with the specific customer KMS key that wrapped it.

The practical consequence of this design: even in a scenario where BYOVault’s own infrastructure was fully compromised, an attacker would gain no ability to decrypt a BYOK-protected file’s content without also separately compromising that customer’s own KMS key.

Under the default path, compromise of the shared master key alone is sufficient to derive every default-path tenant’s key. BYOK removes that shared dependency entirely, at the level of an individual file.

Opt-in, per tenant, and never retroactive

BYOK is configured per tenant, not account-wide, through an explicit consent-then-configure flow. A tenant must acknowledge the setup before a key can be activated.

The supplied KMS key is validated with a real wrap/unwrap round-trip before it is saved, so a misconfigured key is caught immediately rather than surfacing later as a failed backup or restore.

Activating BYOK does not touch anything already backed up — it takes effect only for files uploaded from that point forward.

Mixed estates are normal, not an error state

A tenant can have older files still encrypted under the shared master key and newer files encrypted under BYOK at the same time. Activating BYOK never re-encrypts or re-wraps anything already stored. Every file stays associated with the key configuration that protected it, so older and newer files are each restored correctly regardless of which path protected them.

This per-file tracking is also what makes it safe for a tenant to later configure a different KMS key or provider: a file already wrapped under an earlier configuration continues to record which configuration wrapped it, so it can still be unwrapped correctly on restore even after the tenant’s active configuration has moved on.

Two providers, two distinct architectures

AWS KMS and Azure Key Vault satisfy the same envelope-encryption model above, but the authorization path BYOVault uses to reach a customer’s key is genuinely different between the two providers — not a cosmetic difference in setup steps. See BYOK on AWS KMS: Architecture and BYOK on Azure Key Vault: Architecture for how each provider’s trust model actually works. To configure either one on a tenant, see Set Up BYOK on AWS KMS and Set Up BYOK on Azure Key Vault.

Key rotation is not a supported operation

There is no supported workflow for rotating a BYOK key in place and having existing files re-wrapped under the new one. Each file’s wrapped key stays tied to the KMS configuration that wrapped it. See Key Availability & Failure Behavior for what happens if a configured key becomes unreachable, disabled, or deleted.

PreviousThe Shared Master Key NextBYOK on AWS KMS: Architecture