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:
openssl rand -base64 32The 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".
Back up ENCRYPTION_KEY somewhere that is not the database it protects. If it is lost, every stored secret in every project is unrecoverable: there is no reset and no recovery key. A database backup without the master key is a backup of ciphertext.
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.
Stop the app
Running servers hold the old key in memory. Once rotation commits they can no longer unwrap any project key.
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:
openssl rand -base64 32 # store this before going further
NEW_ENCRYPTION_KEY='<the new key>' enveil-server rotate-master-keyRe-wrapped 12 project key(s) under master key 3fa9c1d07e2b4a85.
Set ENCRYPTION_KEY to the new key, then start the app.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.