Key Management API

A unified interface for the complete cryptographic-key life-cycle

1 · Purpose

The Key Management endpoints give applications crypto-agile control over every key stored in AnkaSecure API — from classical RSA / ECC to post-quantum ML-KEM, ML-DSA, Falcon, SLH-DSA and symmetric AES variants.

All operations are idempotent, return consistent RFC 7807 envelopes on error, and are wired to the platform’s life-cycle engine (usage quotas, expiry dates, rotation chains).

2 · Endpoints (tag `Key Management`)

HTTP Verb	Path	Summary	Typical Use
POST	`/api/key-management/keys`	Generate Key	Create a brand-new key (PQC, classical or symmetric).
GET	`/api/key-management/keys`	List Keys	Enumerate all stored keys — never returns private material.
PATCH	`/api/key-management/keys/{kid}`	JSON Merge-Patch	Update limits / expiry / labels in place (RFC 7396).
POST	`/api/key-management/keys/{kid}/actions/revoke`	Revoke Key	Set status → `REVOKED` (irreversible).
POST	`/api/key-management/keys/{kid}/rotations`	Rotate Key	Immediate synchronous rotation to a successor key.
DELETE	`/api/key-management/keys/{kid}`	Remove Key	Hard delete (use with caution).
GET	`/api/key-management/supported-algorithms`	Supported Algorithms	Discover every `<kty, alg>` pair and its life-cycle state.

3 · Core Schemas (OpenAPI `#/components/schemas/`)*

Schema	Used by	Purpose
KeyGenerationRequest	`POST /keys`	Parameters for deterministic or random key generation.
KeySummaryResponse	`GET /keys`	Minimal key view for bulk listings.
ListKeysResponse	`GET /keys`	Wrapper around multiple `KeySummaryResponse` entries.
RotationRequest	`POST /keys/{kid}/rotations`	Successor-key payload for an immediate rotation.
SupportedAlgorithm	`GET /supported-algorithms`	Crypto-agility catalogue.

4 · Generate Key — Quick Start

POST /api/key-management/keys
Content-Type: application/json
Authorization: Bearer <JWT>

{
"kid"       : "pqk-mlkem-768",
"kty"       : "ML-KEM",
"alg"       : "ML-KEM-768",
"keyOps"    : ["encrypt","decrypt"],
"exportable": true,
"expiresAt" : "2035-12-31T23:59:59Z",
"softUsageLimit": 40000,
"maxUsageLimit" : 50000
}

Code	Meaning
201 Created	New key stored successfully.
200 OK	Same public key already existed --- metadata updated (idempotent).

Lifecycle warnings (expiry, quotas) appear only when the key is used by Secure or Secure Streaming endpoints.

5 - Revocation

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

- 204 No Content --- status switches to REVOKED; the key becomes cryptographically unusable.

6 - Rotation --- friction-less migration

POST /api/key-management/keys/{kid}/rotations
Content-Type: application/json
Authorization: Bearer <JWT>

{
  "newKey": {
    "kid"       : "pqk-hqc-192-v1",
    "kty"       : "HQC",
    "alg"       : "HQC-192",
    "keyOps"    : ["encrypt", "decrypt"],
    "exportable": true
  }
}

| Code | Result | |----------------------------------|-------------------------------------------------------------------------------------------| | 200 OK + KeyExportResponse | Rotation executed synchronously; response describes the successor key. | | 409 Conflict | Destination key's security level is lower or keyOps differ from the original key. |

Rules enforced by the engine

securityLevel(new) ≥ securityLevel(old)
keyOps(new) ⊇ keyOps(old) --- operations stay compatible.

Key-chain model: oldKey.nextKid → newKid ‖ newKey.previousKid → oldKey

7 - Supported Algorithms --- choose the right primitive

Consult the machine-readable list first, then read the rationale in Supported Algorithms

GET /api/key-management/supported-algorithms

[
  {
    "kty"          : "ML-KEM",
    "alg"          : "ML-KEM-768",
    "keyOps"       : ["decrypt", "encrypt"],
    "status"       : "RECOMMENDED",
    "securityLevel": 3,
    "standards"    : ["BSI", "ANSSI", "NIST", "ENISA"]
  },
  {
    "kty"          : "oct",
    "alg"          : "CMAC-AES-128",
    "keyOps"       : ["verify", "sign"],
    "status"       : "LEGACY",
    "sunsetDate"   : "2025-12-31",
    "advisory"     : "Migrate to 192-/256-bit keys.",
    "securityLevel": 1,
    "standards"    : ["ENISA", "BSI", "ANSSI", "NIST", "ISO"]
  },
  {
    "kty"          : "XMSS",
    "alg"          : "XMSS",
    "keyOps"       : ["verify", "sign"],
    "status"       : "RECOMMENDED",
    "securityLevel": 1,
    "standards"    : ["NSA", "BSI", "NIST", "ISO", "ETSI"]
  },
  {
    "kty"          : "RSA",
    "alg"          : "RSA-2048",
    "keyOps"       : ["decrypt", "sign", "verify", "encrypt"],
    "status"       : "RECOMMENDED",
    "sunsetDate"   : "2025-12-31",
    "advisory"     : "Consider migrating to RSA-3072."
  }
]
...
...
...

| Field | Meaning | | --- | --- | | status | RECOMMENDED -- safe for new deployments - LEGACY -- transitional only. | | securityLevel | Relative strength (1 low → 5 highest); used by the rotation engine. | | standards | External bodies that endorse / specify the algorithm. | | sunsetDate | Last day to start new usage; existing data remains decryptable. | | advisory | Human guidance for architects and compliance teams. |

8 - Error Model (RFC 7807)

Code	`type` URI	Trigger
400	`/errors/invalid-input`	Missing fields, malformed Base64, invalid merge-patch.
404	`/errors/not-found`	Unknown `kid`.
409	`/errors/conflict`	Algorithm mismatch, duplicate `kid`, invalid life-cycle transition.
413	`/errors/payload-too-large`	Request body > 5 MiB.
500	`/errors/internal`	Unexpected keystore or crypto-engine failure.

Problem documents embed a millisecond timestamp and respect Accept-Language (en / es).

9 - Security

Every call requires a Bearer JWT issued by your Auth API\ (see securitySchemes.bearerAuth in the OpenAPI specification).