Envelope encryption, in plain terms

When we built Shush, our secrets manager, the core question was simple to state and easy to get wrong: how do you store thousands of other people's secrets so that a database leak doesn't hand an attacker the keys to everything?

The naive answer is one strong encryption key for the whole system. It works, and it's a trap. Rotating that key means re-encrypting every secret you hold, in one nervous operation. And a single leaked key exposes every customer at once. You've built one lock for ten thousand doors.

The envelope idea

Envelope encryption fixes this by using keys to encrypt other keys — like sealing a letter, then sealing the letter inside a stronger envelope.

• Each organisation gets its own data key. Their secrets are encrypted with it, and only it.
• That data key isn't stored in the clear. It's encrypted by a master key that never touches the database.
• To read a secret: unwrap the org's data key with the master key, then decrypt the value. Both layers are AES-256-GCM, which also detects tampering.

The payoff is in the blast radius. One organisation's data key only ever exposes that organisation. Rotating a single tenant's key doesn't touch anyone else's. The master key lives apart from the encrypted data, so a stolen database dump is just ciphertext.

Security isn't one strong wall. It's making sure a breach in one place stays in one place.

The boring parts that matter more

Encryption is the easy half. The decisions that actually keep secrets safe are less glamorous:

• Two-factor on every account, no exceptions. A secrets manager guarded by a password alone is theatre.
• Audit logs you can read. Every read, write and rotation, with who and when — useless if no one can follow them.
• Secrets that never hit disk. Our CLI injects values straight into a process's environment at runtime, so they never land in a plaintext .env waiting to be committed.

None of this is novel cryptography — and that's the point. Good security engineering is mostly the discipline to use well-understood primitives correctly, and to keep the blast radius small when something inevitably goes wrong.