KMS integration

Secrets Manager and KMS integration

Secrets Manager is a consumer of Key Management Service (KMS). Every secret value is encrypted with a customer-chosen KMS key before storage.

Relationship to KMS

Aspect	KMS	Secrets Manager
Purpose	Key management and crypto primitives	Stored secret values with versioning
Identity	Key identity/slug	Path string
Encryption	Direct encrypt/decrypt API	Automatic via bound KMS key
Key choice	Per operation (encrypt API)	Fixed at secret create
Supported key types	Many (symmetric, asymmetric, HMAC)	Symmetric encryption keys only

Key binding

At secret creation, you specify kmsKeyIdentity — the regional symmetric KMS key used to encrypt all versions of that secret.

Property	Behaviour
Binding time	Set at create
Mutability	Immutable — cannot be changed after create
Scope	Key must be in the same region as the secret
Versioning	Each secret version is encrypted; KMS key rotation does not require re-encrypting secret values

To use a different KMS key, create a new secret at a new path (or delete and recreate at the same path after confirming no consumers depend on it).

Supported key types

Only symmetric encryption keys are supported:

Key type	Supported
`aes128-gcm96`	✓
`aes256-gcm96`	✓
`chacha20-poly1305`	✓
Asymmetric keys	✗
HMAC keys	✗

The bound key must be active at create time and for all value read/write operations.

Key state impact

KMS key state	Metadata APIs	`getSecretValue` / `putSecretValue`
`active`	✓	✓
`disabled`	✓	✗ (`400`)
`pending_deletion`	✓	✗ (`400`)

Disabling or deleting a KMS key breaks secret value operations for all secrets bound to that key. Metadata remains readable so you can identify affected secrets.

Before disabling or deleting a KMS key, confirm no active secrets are bound to it. The console should warn when kmsKey.status !== "active".

Underlying crypto operations

Each getSecretValue and putSecretValue triggers KMS decrypt and encrypt on your behalf. These appear in the audit log as kms.decrypt and kms.encrypt entries in addition to Secrets Manager audit events.

A single reveal produces both secrets.get_value and kms.decrypt.

Prerequisites

Requirement	Description
`secrets` feature gate	Secrets Manager must be enabled
`kms` feature gate	KMS must be enabled
Regional KMS endpoint	KMS must be available in the secret’s region
Active symmetric key	Bound key must support encryption and be active

If KMS is not available in the region, crypto operations return 503 Service Unavailable.

Key selection guidance

Create dedicated symmetric KMS keys per environment or sensitivity tier:

Production secrets → production KMS key
Staging secrets → staging KMS key
Shared infrastructure secrets → separate infra key

See Creating keys and Key types.