Secret and crypto key versioning

Vault treats both secrets and crypto keys as named containers of immutable versions. A secret never holds its payload directly; the bytes live in its versions. A crypto key never holds its material directly; the material lives in its versions. The version model is the key to using either one correctly.

Versions are immutable and numbered

Every version has a number that increases by one within its parent, and once written a version’s material is never changed. Adding a payload to a secret appends a new version rather than overwriting the last one; rotating a crypto key produces a new version and makes it the default for new operations. This append-only shape is what makes rollback and audit possible: an earlier version still exists unless you explicitly destroy it.

Lifecycle states

A version moves through a small set of states:

• Enabled: usable, and the one a latest-version lookup returns.
• Disabled: kept but taken out of rotation. You can still read or decrypt it by naming the version explicitly, and re-enable it later. The latest-version lookup skips it.
• Destroyed: the material is permanently gone and unrecoverable.

Crypto keys add one step before destruction: a version can be scheduled for destruction, which leaves a recovery window before the engine permanently deletes the material. Destroying is always terminal, and once a version is destroyed, any ciphertext encrypted under it can no longer be decrypted.

Resolving the latest version

When you read a secret or run a crypto operation without naming a version, vault resolves to the latest enabled version. Disabling a version is the safe, reversible way to retire it; destroying is the irreversible one.

For crypto keys you can also set a floor so that versions below it can no longer decrypt, retiring old material in a controlled way. To carry existing ciphertext forward after a rotation without ever exposing plaintext, ask vault to re-encrypt it under the current version.

What is stored where

The control plane stores only metadata: the version number, its state, timestamps, and, for a secret, a checksum of the payload. The secret bytes and the key material live exclusively in qibdo’s vault engine. Because the checksum is an etag over the payload, a client can tell whether a secret changed without reading the bytes back, and the audit trail can reference an operation by that hash rather than the secret itself.

For the task-side walkthrough, see store and read a secret.