Skip to main content

​
Tenant KMS Key Rotation

Rotation creates a new tenant master key version wrapped under your KMS key. New writes immediately use the new version; existing ciphertext stays readable because the retired version remains available for unwrap. A background rewrap job migrates existing data to the new version automatically.

​
What happens during rotation

  1. A new 32-byte master key is generated and wrapped using your KMS key → new active version
  2. The previous active version is moved to retired
  3. New encrypts (new secrets, new CA key versions, new DB passwords) use the new active version immediately
  4. Existing ciphertext wrapped by the retired version continues to unwrap successfully
  5. A background rewrap job is enqueued to re-encrypt all existing tenant data under the new active version

​
When to rotate

  • Suspected compromise of the old master key version
  • Scheduled compliance rotation (annual, quarterly — check your policy)
  • Post-breach seal/unseal cycle — rotate after any event where you were unsure of KMS security
  • KMS key rotation on the cloud provider side — rotate the KnoxCall master key after rotating the underlying KMS key so new wraps use the new KMS key version

​
How to rotate

​
Via admin UI

  1. Go to Settings → Security → Tenant Master Key → Customer KMS
  2. Click Rotate key
  3. Confirm the dialog

​
Via API

Rotation requires a recent step-up verification within a 5-minute window. Complete a fresh step-up (passkey or 2FA) via POST /auth/passkey/verify-step-up or POST /auth/2fa/verify-step-up on the same admin session immediately before calling rotate — the gate checks the server-side verification record, so no separate step-up header is sent on the rotate request itself.
Response:
rewrap_lease_id is the identifier for the background rewrap job described below. It is null if the rewrap lease failed to issue — the rotation itself still succeeded in that case; contact support to trigger the rewrap manually.
Rotation is non-reversible. Once the old version is retired, you cannot make it active again. You can still decrypt existing data, but new writes will use the new version. If you revoke the old version later, anything written under it becomes permanently unreadable. Cannot be called while the tenant is sealed — unseal first.

​
Background rewrap

After rotation completes, KnoxCall immediately enqueues a tenant_rewrap background job. This job re-encrypts all existing tenant data under the new active master key version:
  • Processes 100 rows per batch (interleaved: 50 from secret_environment_configs, 50 from integration_configs)
  • Batches run every 5 seconds
  • The target_version is pinned at job creation time — even if another rotation occurs mid-flight, all rows processed by this job land on the same version (prevents split-version state across a rotation boundary)
  • Rows already on the target version are skipped and counted as complete
  • The lease expires after 7 days — if a persistent KMS error prevents rewrap from completing in that window, contact support
You can track rewrap progress via Automation → Agents in the admin UI. The old retired version remains available for decryption throughout the rewrap and beyond, until you explicitly revoke it.

​
Audit trail

Every rotation is logged in the critical audit chain: The log entry includes new_version, wrap_method, rewrap_lease_id, and the IP that triggered it.

​
Key version lifecycle

Revoking a retired version is a destructive, permanent action. Use it only when you need to guarantee that data written under that version can never be recovered — for example, data destruction per GDPR right-to-erasure.

​
Checking key versions

The response keys array contains all versions:

Sealed state and unseal

What happens if KMS becomes unreachable after rotation

Tenant master key concepts

Version lifecycle and cryptographic erasure background

Tenant KMS API reference

Rotate endpoint reference

Audit Logs

View the rotation audit trail