Keys and encryption
Which KMS key protects a secret, what happens to the secret when that key is disabled or deleted, and how the keys themselves are held.
Every version of a secret is encrypted with AES-256-GCM under one customer managed key (CMK) from
KMS, the key named when the secret was created. A new organization has one key, named default;
the console's Create secret pre-selects the organization's default key, and the API and CLI
require keyId. A source's credential is encrypted under the key you choose when you connect it,
else under the default key.
A secret's key cannot be changed. To move a secret to another key, reveal its value, delete the
secret and create it again under that key: a second secret of the same name in the same
environment is refused with 409 while the first exists. The new secret starts at version 1 with
no grants, and app variables bound to the old one lose their value until you bind the new one.
When the key is not enabled
While a secret's key is disabled, scheduled for deletion, or (for a key with imported material) without material, the value cannot be read:
- revealing it is refused with
409"Encryption key is unavailable"; - rotating it is refused with
409"Key is not enabled"; - a deployment or a workflow job that needs it fails;
- a synced secret whose upstream value changed fails with "its encryption key is not enabled, so the new value cannot be stored" and keeps its last value.
The secrets list marks the row Key disabled, Key being deleted or Key has no material, and the secret's panel says why. Enabling the key again, or cancelling its deletion, makes the value readable again.
Deleting a key
A key that still encrypts secrets cannot be scheduled for deletion: KMS refuses with 409 and names
the secrets. Move them to another key as above, or delete them, first. The organization's default
key cannot be scheduled for deletion either, until another key is the default. A secret whose key is gone
cannot be recovered.
Key custody
- Software, not a hardware security module. Encryption and decryption run in the platform's own processes. No HSM is involved.
- One platform key at the root. Every CMK's material is stored wrapped by a single platform key held by the control plane. Whoever holds that key and a copy of the platform's database can unwrap every CMK.
- Values are decrypted in the control plane and handed only to the consumer that reads them:
the console or API caller with
secrets:GetSecretValue, an app's machine at deployment, a workflow job. See What runs where.
Related
- Keys (KMS): create, disable and delete keys, bring your own key, key custody, SSH key pairs.
- Secrets and versions
- Security in Secrets