Rotation and versioning

Every crypto key in KnoxCall is versioned. New encryptions always use the latest active version; old ciphertext keeps decrypting against whatever version originally produced it. Rotation moves the active pointer forward without breaking anything that’s already encrypted.

The version lifecycle

v1 active   ──rotate──▶  v1 retired  +  v2 active   ──rotate──▶  v2 retired + v3 active  ──destroyVersion──▶  v1 destroyed

Each version is in one of three states:

active — used for new encryptions. Exactly one per key at any time.
retired — kept around so old ciphertext under that version still decrypts. As many as you’ve rotated.
destroyed — cryptographic erasure. The wrapped key bytes are wiped and the row stays as an audit marker. Ciphertext under a destroyed version is permanently unreadable.

Rotating a key

curl -X POST https://api.knoxcall.com/admin/crypto/keys/customer-pii/rotate \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "X-Tenant-ID: $TENANT_ID"
# → { "new_version": 2 }

What happens, atomically inside a single transaction:

A new 256-bit key is generated and wrapped with the tenant master key.
The new version row is inserted as active.
The previous active version is flipped to retired.
The key’s current_version pointer is updated.

encrypt calls from this point forward emit knoxcall:v2:... ciphertext. decrypt calls handle either v1 or v2 ciphertext seamlessly.

When to rotate

Reason	How often
Routine hygiene (compliance)	Every 90 days
After a personnel change with key access	Immediately
After a suspected compromise	Immediately + rewrap + destroy old version
Pre-emptive before destroying the active version	Always (you can’t destroy `active`)

Rotating is cheap. Decrypting from old versions is also cheap. The only meaningful “cost” of holding many retired versions is audit-trail clutter.

Rewrap: migrate ciphertext to a new version

Rotating doesn’t re-encrypt existing data. Old ciphertext keeps decrypting against retired versions. To migrate it:

curl -X POST https://api.knoxcall.com/admin/crypto/keys/customer-pii/rewrap \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "ciphertext": "knoxcall:v1:G2x..." }'
# → { "ciphertext": "knoxcall:v2:K9p...", "key_version": 2 }

rewrap decrypts the old ciphertext with the retired version, re-encrypts with the active version, and returns the new ciphertext — the plaintext never crosses the wire. The operation runs entirely on KnoxCall’s side. The typical migration loop:

for each row in your_table where ciphertext_version < current_version:
  new_ct = POST /admin/crypto/keys/<name>/rewrap { ciphertext: row.ct }
  UPDATE your_table SET ct = new_ct WHERE id = row.id

After every row is rewrapped, you can safely destroy the old version.

Destroying a version (cryptographic erasure)

curl -X DELETE https://api.knoxcall.com/admin/crypto/keys/customer-pii/versions/1 \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "X-Tenant-ID: $TENANT_ID"

What this does:

Refuses with 409 deletion_not_allowed if deletion_allowed = false on the parent key (the safety latch — see below for how to raise it).
Refuses with 409 active_version if the version is active — rotate first.
Wipes the wrapped key bytes from the row, flips status to destroyed, records who and when.

Any ciphertext that named this version in its prefix is gone forever. There’s no off-site backup. This is the feature, not a bug — it’s the right-to-be-forgotten primitive.

`deletion_allowed`

Every key ships with deletion_allowed = false. Flipping it to true is a deliberate, audit-logged action that says “I’m about to destroy a version on purpose.” Flip it from the API:

curl -X PATCH https://api.knoxcall.com/v1/crypto/keys/customer-pii \
  -H "Authorization: Bearer $KC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"deletion_allowed": true}'

…or from the admin UI: Crypto Keys → your key → Versions → Allow version destruction. The UI toggle requires a recent second-factor verification; the /v1 call is bounded by the credential’s transit:manage grant instead, because there is no human on the machine plane to re-authenticate. Pattern we recommend:

Rewrap all data to the new active version.
Confirm in a query that no row in your DB still has ciphertext at the version you’re about to destroy.
PATCH /v1/crypto/keys/<name> with {"deletion_allowed": true}.
DELETE /versions/<old>.
PATCH it back to {"deletion_allowed": false}.

Every flip writes a transit.key.deletion_allowed audit row recording the previous and new value, so “who armed this key, and when” is answerable after the fact.

Before 2026-09, this latch had no writer on any surface: it was false for every key, the admin UI’s Destroy button was therefore never shown, and a DELETE of any version answered 500. Both are fixed — the refusal is now a 409 with a deletion_not_allowed code, and the latch is settable on both surfaces as above.

What rotation doesn’t do

It doesn’t break existing decryption — old ciphertext keeps working until you destroy the old version.
It doesn’t re-encrypt existing data — that’s rewrap.
It doesn’t change the ciphertext format — same prefix, just a higher version number.
It doesn’t propagate to bundled-mode agents instantly — they pick up the new version on their next session-bundle refresh.

Key cache behaviour

Unwrapped key versions are cached in memory for 5 minutes after first use. Rotation invalidates the previous active entry; destroy invalidates the destroyed entry. You don’t need to worry about the cache day-to-day — it’s an internal performance optimisation, not something you manage.

Audit log markers

Audit action	Means
`transit.key.create`	A new key was minted (version 1 active)
`transit.key.rotate`	New version became active
`transit.encrypt` / `transit.decrypt`	Single op (records key version, not plaintext)
`transit.rewrap`	Ciphertext was rewrapped from one version to another
`transit.key.destroy_version`	Version was cryptographically erased

​Rotation and versioning

​The version lifecycle

​Rotating a key

​When to rotate

​Rewrap: migrate ciphertext to a new version

​Destroying a version (cryptographic erasure)

​deletion_allowed

​What rotation doesn’t do

​Key cache behaviour

​Audit log markers

​See also

Rotation and versioning

The version lifecycle

Rotating a key

When to rotate

Rewrap: migrate ciphertext to a new version

Destroying a version (cryptographic erasure)

`deletion_allowed`

What rotation doesn’t do

Key cache behaviour

Audit log markers

See also