Encryption

Per-project data keys under one master key, with values bound to where they are stored

Two layers of keys

enveil never encrypts a secret directly under the deployment's master key. Each project has its own data key, and the master key only wraps those.

Key Where it lives What it encrypts
Master key (ENCRYPTION_KEY) The server's environment. Never in the database Each project's data key
Project data key The projects table, wrapped under the master key Every value and archived version in that project

Both layers use AES-256-GCM with a fresh random nonce for every encryption. A project's data key is generated when the project is created and is only ever stored wrapped. Unwrapped key material is zeroed in memory when it is dropped.

The indirection buys two things:

  • Rotation is cheap. Changing the master key rewrites one short column per project instead of re-encrypting every value in the database.
  • A project's ciphertext has a single point of destruction. Without its wrapped data key, a project's values cannot be read, wherever copies of the rows ended up.

Values are bound to where they are stored

AES-GCM can authenticate extra data alongside the ciphertext, data that is not encrypted but must match exactly at decryption. enveil uses this to tie each ciphertext to its place:

Ciphertext Bound to
A value Its project, environment and key name
A wrapped data key Its project and the master key that wrapped it

So someone who can write to the database still cannot move ciphertext around. Copy prod's STRIPE_SECRET_KEY row into dev, where a wider-scoped agent could read it, and decryption fails instead of disclosing it. Copy one project's wrapped key into another project's row, and it fails to unwrap. The same holds for renaming a key in place.

This does not protect against an attacker who holds the master key and the database together. It removes the cheaper attack: rearranging rows so that the access checks, which are made against project and environment, let someone read what they should not.

The master key

ENCRYPTION_KEY is 32 random bytes, base64-encoded:

sh
openssl rand -base64 32

The server refuses to start without it, rather than quietly storing plaintext. Each wrapped data key records a short fingerprint of the master key that wrapped it, so a server running with the wrong ENCRYPTION_KEY reports exactly that, naming both fingerprints, instead of a confusing "not found".

Rotating the master key

Rotation is the recovery path for a leaked master key. It unwraps each project's data key with the old master key and wraps it again under the new one. Values are never decrypted or rewritten.

1

Stop the app

Running servers hold the old key in memory. Once rotation commits they can no longer unwrap any project key.

2

Rotate

Generate the new key and store it first. Then run the server binary with the current key still in ENCRYPTION_KEY and the new one in NEW_ENCRYPTION_KEY:

sh
openssl rand -base64 32        # store this before going further
NEW_ENCRYPTION_KEY='<the new key>' enveil-server rotate-master-key
text
Re-wrapped 12 project key(s) under master key 3fa9c1d07e2b4a85.
Set ENCRYPTION_KEY to the new key, then start the app.
3

Switch the key and start

Set ENCRYPTION_KEY to the new key, back it up, and start the app.

Every project is re-wrapped in one transaction, so either all projects move to the new key or none do. Projects already under the new key are skipped, so running the command again after a success is harmless.

Self-hosting the server? See Self-hosting for the rest of its configuration.