Skip to main content

​
Encrypting under your own key

By default a secret’s versions are encrypted under a platform-managed key. Bind the secret to one of your own KMS keys at creation to use that instead:
On Create Secret, open the Encryption card and choose a key under Encryption key rather than Platform-managed key (default).The picker offers your enabled symmetric (aes-256) keys with encrypt_decrypt usage in the selected region.
The key must be one of yours, in the same region, enabled, and pinned to encrypt_decrypt. Pass its UUID, full CRN or account-scoped name in kms_key. The binding keeps the original key identity even if its name is reused after deletion. A replacement key cannot decrypt the original secret.
It must also be symmetric — aes-256. An RSA key with encrypt_decrypt usage is refused with 400 KMS_INVALID_KEY_SPEC, because every version is sealed with the secret’s identity bound in as encryption context and RSA-OAEP has nowhere to carry one. Accepting the key would drop that binding silently, so it is refused at creation instead.

​
What it changes

Binding a secret to your key does not change the API surface — value reads and writes look identical. What changes is that the key becomes a control you hold:
  • Disable the key and reads start failing with 409 KMS_KEY_DISABLED. That error travels to you as itself, not as a 500 — the key state is yours, and re-enabling the key restores reads.
  • Schedule the key for deletion and reads fail with 409 KMS_KEY_PENDING_DELETION for the whole window.
  • Let that window elapse and every version of every secret under that key is permanently unreadable. The ciphertext is still in the database; nothing can open it.
The binding is fixed for the life of the secret. kms_key is accepted only on create, and PATCH edits just description and tags — moving a secret to a different key means re-wrapping every version, so create a new secret and retire the old one instead.

​
Versions are bound to their secret

Whichever key is used, the ciphertext of every version is sealed with the secret’s account and secret id as encryption context. A stored blob therefore only decrypts as the version of the secret it was written for — it cannot be lifted out of the database and replayed as the value of a different secret, even one encrypted under the same key. Secret metadata returns kms_key as a ResourceRef with id, crn and name. It is omitted for platform encryption. A customer-managed key cannot be scheduled for deletion while this secret depends on it, including during the secret’s recovery window. The secret and all its versions must be purged first.