Key-Management Overview

Audience

Developers who need one API for both RSA and post-quantum keys.

Security Leads / CISOs who must prove crypto-agility, rotation, auditability.

1 ▪ Why Crypto-Agility?

Algorithms age, threat-models change.
AnkaSecure lets you replace RSA-2048 with ML-KEM-768—or any other supported pair—without touching ciphertext or application code.

Feature	Benefit
Uniform JSON model	One envelope for RSA, AES, ML-KEM, Falcon, …
Immediate + scheduled rotation	Swap keys atomically or queue a future swap in one call
Soft & hard limits	Usage / time-based warnings before failure
Streaming ops	Migrate petabyte archives without exposing plaintext

2 ▪ Universal Key Model

{
  "kid": "myML-KEMKey234",

  "kty": "ML-KEM",
  "alg": "ML-KEM-768",
  "publicKey": "<BASE64…>",

  "keyOps": ["encrypt", "decrypt"],
  "exportable": true,

  "createdAt": "2025-03-17T00:37:44Z",
  "expiresAt": "2030-05-31T23:59:59Z",
  "softLimitExpiration": "2029-12-31T23:59:59Z",

  "usageCount": 11,
  "lastUsedAt": "2025-03-19T16:55:54Z",
  "softUsageLimit": 40000,
  "maxUsageLimit": 50000,

  "status": "ACTIVE",
  "previousKid": null,
  "nextKid": null,

  "hash": "b08dca00c20162e618d4a5a0459e68ee8f4f90d9cb7c48882afb1f98006f5f39"
}

Field	Meaning
kid	Human & forensic identifier
kty / alg	Algorithm family + exact parameter-set
keyOps	Allowed usages: encrypt / decrypt / sign / verify
exportable	If `false`, private bytes never leave the store
Limits	Soft & hard counters for usage and time
Links	`previousKid` ↔ `nextKid` chain each rotation

3 - Lifecycle State-Machine

stateDiagram-v2
[*] --> ACTIVE

    ACTIVE --> PENDING_ROTATION : rotation scheduled
    PENDING_ROTATION --> ROTATED : rotation executed

    ACTIVE --> REVOKED
    PENDING_ROTATION --> REVOKED
    ROTATED --> REVOKED

    ACTIVE --> EXPIRED
    PENDING_ROTATION --> EXPIRED
    ROTATED --> EXPIRED

    ROTATED --> ARCHIVED
    EXPIRED --> ARCHIVED
    REVOKED --> ARCHIVED

    ARCHIVED --> DELETED_LOGICAL : audit window elapsed
    DELETED_LOGICAL --> [*]

Status	Operational Meaning
ACTIVE	Full read / write usage.
PENDING_ROTATION	Key marked for swap; still usable until cut-over.
ROTATED	Successor generated; use `nextKid` for new encrypt/sign; may still decrypt/verify legacy data.
EXPIRED	Time limit passed; decrypt/verify only.
REVOKED	Manually frozen; decrypt/verify only (e.g., key compromise).
ARCHIVED	Read-only long-term retention; visible to custodians, hidden from apps.
DELETED_LOGICAL	Retained offline for legal hold; invisible to APIs.

4 - Key-Management Endpoints

Operation	Method & Path	Typical Scenario	Demo Flow
Generate / update key	`POST /api/key-management/keys`	Provision RSA-4096 or ML-KEM-1024	#14
List keys	`GET /api/key-management/keys`	Inventory & dashboards	--
Export public key	`GET /api/migration/keys/{kid}`	Distribute public part for client-side encrypt	#10
Rotate key	`POST /api/key-management/keys/{kid}/rotations`	RSA-2048 → ML-KEM-768 upgrade	#23
Merge-patch limits	`PATCH /api/key-management/keys/{kid}`	Raise usage caps, extend expiry	#18
Revoke key	`POST /api/key-management/keys/{kid}/actions/revoke`	Compromise response	#17
Delete key	`DELETE /api/key-management/keys/{kid}`	Policy-driven purge (post-archive)	--
Supported algorithms	`GET /api/key-management/supported-algorithms`	Build-time & runtime discovery	#19

5 - Supported Algorithms (2025-05)

Always fetch the live list with

GET /api/key-management/supported-algorithms.

👉 Full matrix & migration guide --- security levels, performance, sunset dates.

Category	Algorithms
Post-Quantum --- KEM	ML-KEM-512/768/1024, FrodoKEM-1344, HQC-256
Post-Quantum --- Sign	ML-DSA-44/65/87, Falcon-512/1024, SLH-DSA-* (SHA2/SHAKE, 128/192/256 F/S), XMSS
Classical Asymmetric	RSA-1024/2048/4096/8192, EC-256/384/521
Classical Symmetric + MAC	AES-128/192/256, CMAC-AES-128/192/256
One-time key (`oct`)	Arbitrary-length secrets

Each algorithm entry includes status, sunsetDate, securityLevel, and standards so you can warn users before NIST deprecations.

6 - Rotation vs Patch --- Quick Guide

Goal	Call	Latency	Data Migration
Quantum upgrade	`POST .../rotations`	1 request	None --- successor chosen automatically
Raise limits / extend TTL	`PATCH .../keys/{kid}`	1 request	None
Kill compromised key	`.../actions/revoke`	< 1 s	None

7 - Learn by Example

Flow 14 --- generate → export → revoke → delete
Flow 17 --- revoke & policy headers
Flow 18 --- JSON Merge-Patch (RFC 7396)
Flow 23 --- RSA-2048 ⇒ ML-KEM-768 immediate rotation
Flow 10 --- export and decrypt with public key
Flow 19 --- runtime algorithm discovery

All flows live under /docs/sdk/integration/.