secretsmgr handbook
Editor sign-in

How the layers stack

Reading a secret means peeling the envelopes from envelope encryption in order. Your key provider (where your key lives) unlocks your private key; your private key unlocks the vault key; the vault key unlocks the data key; the data key unlocks the value.

your key provider          (passphrase · security key · cloud KMS)
        │ unlocks
        ▼
your private key           (never leaves your machine)
        │ unlocks                                 stored once per member
        ▼
vault key                  (one per vault)   ──►  everything right of here
        │ unlocks                                 is stored a single time
        ▼
data key                   (one per secret)
        │ unlocks
        ▼
the value                  (what you actually wanted)

Every encrypted file is also stamped with where it belongs: which organization, which vault, which secret, which version number. Move one somewhere else and it simply refuses to decrypt. That closes off a whole family of attacks where someone shuffles files around to make your application load the wrong credential.