Skip to content

Key Rotation & Revocation

Production-ready lifecycle management for every cryptographic key

1. Introduction

Anka Secure implements a crypto-agile lifecycle that lets you revoke or rotate keys without disrupting ongoing cryptographic operations.
Both actions are:

  • Atomic – the key‐store is always in a consistent state.
  • Auditable – every change is retained for forensics and compliance.
  • Chain-aware – the previousKid ↔ nextKid links let you walk the full history of a secret.

The lifecycle is exercised end-to-end in the new SDK scenarios:

Scenario Purpose Reference
17 Immediate revocation & attempted reuse (expect failure) ExampleScenario17
18 Online upsizing of limits via RFC 7396 merge-patch ExampleScenario18
19 Discovery of RECOMMENDED algorithms and smoke-test rotation after a soft-limit warning ExampleScenario19

2. Key Revocation

Revocation is irreversible: once a key is revoked it can never be used for encrypt, decrypt, sign or verify again.
The material remains in secure storage for evidence, and you may still export the public part for historical verification.

2.1 Endpoint (Synchronous)

POST /api/key-management/keys/{kid}/actions/revoke

* **Success** --204 No Content(Beautiful-API: empty body). * **Failure** --404 Not Foundif the *kid* does not exist. * **Security** --bearerAuthorrapidApiKey`.

2.2 Resulting Metadata

``json { "kid" : "finance-rsa-2048-2023", "status" : "REVOKED", "revokedAt" : "2025-05-11T09:42:17Z", "nextKid" : "finance-mlkem-768-2025" }

If the key was already part of a rotation chain, its nextKid keeps the link intact so decrypt / verify operations on older data can locate the valid successor.

3. Key Rotation

Rotation replaces an active key with a fresh one that has identical cryptographic characteristics (kty + alg), minimising the window in which a single secret can be compromised.

3.1 Endpoint (Immediate or Scheduled)

POST /api/key-management/keys/{kid}/rotations

Field Description Required
scheduledAt ISO-8601 UTC timestamp for deferred execution. no
newKey Full KeyGenerationRequest for the successor. yes

  • Execute now -- omit scheduledAt. The call returns 200 OK and the complete KeyExportResponse of the new key.

  • Schedule later -- provide a future scheduledAt. The call returns 202 Accepted with a Location header pointing to the rotation-job resource.

    • Poll GET /api/key-management/rotation-jobs/{jobId} until status = SUCCEEDED.

3.2 Metadata Evolution

Field Before Rotation (oldKid) After Rotation (oldKid) After Rotation (newKid)
status ACTIVE ACTIVE (until expiry) ACTIVE
nextKid null newKid null
previousKid null null oldKid

Rotated chains are unbounded; you may traverse links until the first key is finally purged.

3.3 Limit & Expiry Triggers

A rotation can also be initiated server-side when a key crosses one of its soft limits:

  • Soft usage limit -- usageCount ≥ softUsageLimit

  • Soft time limit -- now ≥ softLimitExpiration

The rotation engine mirrors every mutable field unless overridden in the newKey payload (e.g., higher limits or longer expiry).

4. Operational Guarantees

  1. No downtime -- encryption seamlessly switches to nextKid while decryption remains possible with any key in the chain.

  2. Consistent warnings -- headers such as X-Key-Usage-Limit-Warning and X-Key-Expiration-Warning propagate to SDK metadata (see scenarios 18 & 19).

  3. Auditability -- all status transitions (ACTIVE → REVOKED, ACTIVE → ROTATED) are journalled with timestamp and operator identity.

5. Developer Checklist

Step Action Endpoint
① Detect approaching limits via warnings[] or licence telemetry. Any Secure / Stream operation
② POST .../keys/{kid}/rotations with a newKey spec. Key Management
③ (If 202) poll rotation job until SUCCEEDED. Key Management
④ (Optional) revoke the predecessor early if compliance requires it. .../actions/revoke
⑤ Update your kid references on the client side (or rely on SDK auto-discovery). ---

Tip\ The SDK automatically follows nextKid links. In most scenarios you keep using the old identifier and the library resolves the active secret for you.

  • ExampleScenario17 -- Revocation lifecycle (non-stream).

  • ExampleScenario18 -- Limit upsizing with JSON merge-patch.

© 2025 AnkaTech Co. All rights reserved.