# 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](what-runs-where.md).

## Related

- [Keys (KMS)](/docs/kms): create, disable and delete keys, bring your own key, key custody, SSH key
  pairs.
- [Secrets and versions](secrets-and-versions.md)
- [Security in Secrets](security.md)
