{"openapi":"3.1.0","info":{"title":"ANKASecure API – Post-Quantum Cryptography API","description":"Quantum-resistant cryptography.\nClassical: AES · RSA · ECC\nPost-quantum: ML-KEM · ML-DSA · Falcon · SLH-DSA · HQC · FrodoKEM","contact":{"name":"AnkaTech Support","url":"https://ankatech.co","email":"info@ankatech.co"},"version":"3.0.0","x-category":"Security","x-long-description":"Classical cryptography API (AES, RSA, ECC) and post-quantum cryptography (ML-KEM, ML-DSA, Falcon, SLH-DSA, HQC, FrodoKEM) for encryption, digital signing and key management.","x-website":"https://ankasecure.co"},"servers":[{"url":"https://{host}:{port}","description":"Parametrised Anka Secure Server (https://host:port)","variables":{"host":{"description":"Hostname or IP address of the server","default":"demo.ankatech.co"},"port":{"description":"TCP port on which the server listens","default":"443"}}}],"security":[{"bearerAuth":[]}],"tags":[{"name":" Key Management","description":" Unified endpoints for creating, importing, listing, exporting, \n removing cryptographic keys (both classical and post-quantum), \n and discovering the dynamically supported algorithms \n for complete crypto-agility.\n "},{"name":" Secure","description":"Endpoints to manage and perform cryptographic operations with symmetric\nand post-quantum/classical asymmetric keys (AES, RSA, ECC, ML-KEM, ML-DSA, Falcon, etc.).\n"},{"name":"Policy Cache Monitoring","description":"Monitor policy cache health (read-only observability)"},{"name":"Interoperability","description":"Continuous interoperability operations for cryptographic collaboration with\nexternal systems using caller-supplied keys (not persisted in keystore).\nSupports signature verification and encryption for cross-platform integration\nwithout importing keys into ANKASecure infrastructure.\n"},{"name":"Migration","description":"One-time migration operations for importing keys, certificates, and legacy\ncryptographic data from external systems (PKCS#12, PKCS#7/CMS). These endpoints\nsupport transitioning legacy cryptographic assets to ANKASecure's post-quantum\ninfrastructure. Keys are imported into the tenant keystore for ongoing use.\n"},{"name":"License Metrics","description":"Operational metrics for license validation monitoring"},{"name":" Secure Streaming","description":"Endpoints to manage fully streaming-based cryptographic operations\nwith symmetric and post-quantum/classical asymmetric keys (AES, RSA, ECC, ML-1024,\nML-DSA, Falcon, etc.).\n"}],"paths":{"/api/migration/stream/convert-pkcs7-to-jose":{"post":{"tags":["Migration"],"summary":"Convert PKCS#7 to JOSE (streaming)","description":"Converts PKCS#7/CMS files of any size to modern JOSE (JWE/JWS) detached format.\n\nThis is a **format conversion** (PKCS#7 container → JOSE container), not an algorithm conversion.\nClassical algorithms (RSA, ECDSA, AES) are preserved or upgraded (CBC→GCM).\n\n**Supported conversions:**\n\n- SignedData (1 signer) → JWS detached JSON\n- EnvelopedData (1 recipient) → JWE detached multipart\n- SignedAndEnvelopedData (1 signer + 1 recipient) → JWE(JWS) detached multipart\n\n**Response format varies by PKCS#7 type:**\n\n**SignedData** returns `application/octet-stream`:\n```json\n{\"protected\":\"eyJhbGc...\",\"signature\":\"dGVz...\"}\n```\n\n**EnvelopedData** returns `multipart/mixed`:\n```\n------ankatech-\nContent-Type: application/jose+json\n\n{\"protected\":\"...\",\"recipients\":[...],\"iv\":\"...\"}\n\n------ankatech-\nContent-Type: application/octet-stream\n\n\n------ankatech---\n```\n\n**Important:**\n- No size limit (processes files of any size)\n- Response does NOT include metadata (signers, recipients, algorithm details)\n- For metadata: Use POST /api/migration/stream/analyze-pkcs7 first\n- Output is directly compatible with POST /api/crypto/stream/reencrypt or /resign\n\n**Prerequisites:** Import signer/recipient keys via POST /api/migration/pkcs12\n\n**Input:** multipart/form-data with 'metadata' (JSON) and 'file' (binary PKCS#7)\n","operationId":"convertPkcs7ToJoseStream","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/Pkcs7ConversionStreamRequest"},"file":{"type":"string","format":"binary"}},"required":["file","metadata"]}}}},"responses":{"200":{"description":"Conversion successful. Format varies: application/octet-stream (JWS for SignedData) or multipart/mixed (JWE for EnvelopedData)","content":{"*/*":{}}},"400":{"description":"Invalid input","content":{"application/problem+json":{}}},"422":{"description":"Conversion not supported or key missing","content":{"application/problem+json":{}}},"413":{"description":"File exceeds size limit","content":{"application/problem+json":{}}}}}},"/api/migration/stream/analyze-pkcs7":{"post":{"tags":["Migration"],"summary":"Analyze PKCS#7 structure (streaming, >5MB files)","description":"Introspects large PKCS#7/CMS binary data and returns structured metadata using streaming (>5MB, up to 100MB).\n\nReturns metadata including signers, recipients, algorithms, certificates, and conversion feasibility.\n\n**Supports:**\n\n- SignedData (1 signer)\n- EnvelopedData (1 recipient)\n- SignedAndEnvelopedData (1 signer + 1 recipient)\n\n**Current support**: Single signer and single recipient only\n**Multi-actor support**: Planned for future release\n\n**Input:** multipart/form-data with optional 'metadata' (JSON) and 'file' (binary PKCS#7)\n","operationId":"analyzePkcs7Stream","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/Pkcs7AnalysisStreamRequest"},"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"Analysis successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pkcs7AnalysisResponse"}}}},"400":{"description":"Invalid PKCS#7","content":{"application/problem+json":{}}},"413":{"description":"File exceeds 100MB","content":{"application/problem+json":{}}}}}},"/api/migration/pkcs12":{"post":{"tags":["Migration"],"summary":"Import PKCS#12 bundle with private keys and trusted certificates","description":"Imports complete PKCS#12 bundle containing private keys and trusted certificates (CAs).\n\n**Supports:**\n- Private keys with X.509 certificates\n- Trusted certificates (Root CAs, Intermediate CAs)\n- Mixed bundles (keys + CAs)\n- Truststore-only files (no private keys)\n\n**Certificate Validation Modes:**\n- STRICT (production): Reject expired/invalid certificates\n- IMPORT_ONLY (recovery): Allow expired with keyOps=[decrypt,verify]\n- SKIP (testing): No validation\n\n**Multi-Key Support:**\n- Single key: Uses kid unchanged\n- Multiple keys (AUTO): Generates kid-{sanitizedAlias}\n- Multiple keys (MANUAL): Uses explicit kidMappings\n\n**Trusted Certificates:**\n- Assigned kids with \"-trust-\" prefix: kid-trust-{sanitizedAlias}\n- Stored in same keystore as private keys\n- Used for PKCS#7/CMS signature verification\n\n**Idempotency:**\n- Reimporting existing entries returns 200 OK with skipped list\n- New entries return 201 Created\n\n**Maximum Size:** 20 MB (configurable via MIGRATION_MAX_PKCS12_SIZE)\n\n**Response:** Returns Pkcs12ImportResponse with private keys, trusted certificates, failures, and skipped entries.\n","operationId":"importPkcs12Bundle","requestBody":{"description":"PKCS#12 import request with optional validation and kid configuration:\n • kid – base identifier for imported entries\n • p12Password – optional PKCS#12 password (null for unprotected)\n • p12FileBase64 – Base64-encoded PKCS#12 file\n • validationMode – optional (STRICT, IMPORT_ONLY, SKIP); uses global config if omitted\n • kidStrategy – optional (AUTO, MANUAL); default AUTO\n • kidMappings – required if kidStrategy=MANUAL; map of alias→kid\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportPkcs12Metadata"},"examples":{"Complete bundle (keys + CAs)":{"description":"Complete bundle (keys + CAs)","value":{"kid":"client-2024","p12Password":"changeit","p12FileBase64":"MIIKvwIBAzCCChAGCSqGSIb3DQEHAaCCCgE...","kidStrategy":"AUTO","validationMode":"IMPORT_ONLY"}},"Truststore only (CAs without private keys)":{"description":"Truststore only (CAs without private keys)","value":{"kid":"truststore-ca-bundle","p12Password":"trustpass","p12FileBase64":"MIIKvwIBAzCCChAGCSqGSIb3DQEHAaCCCgE..."}}}}},"required":true},"responses":{"201":{"description":"PKCS#12 bundle imported successfully (new entries created).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pkcs12ImportResponse"}}}},"200":{"description":"All entries already exist (idempotent reimport).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pkcs12ImportResponse"}}}},"400":{"description":"Invalid PKCS#12 file or password.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"413":{"description":"Payload Too Large: PKCS#12 data exceeds maximum size.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"All entries failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/migration/keys/import":{"post":{"tags":["Migration"],"summary":"Import an existing cryptographic key (symmetric, classical, or post‑quantum).","description":"Accepts public and/or private material to register a key.\nSymmetric keys use kty=oct; post‑quantum KEMs use\nkty=ML‑KEM, etc.\nRefer to GET /api/key‑management/supported‑algorithms for valid values.\n","operationId":"importKey","requestBody":{"description":"Provide publicKey and/or privateKey depending on\nwhether you are importing a partial or full key‑pair. For symmetric keys\n(kty=oct) supply the secret in privateKey.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyImportRequest"},"examples":{"Asymmetric public key (RSA‑2048)":{"description":"Asymmetric public key (RSA‑2048)","value":{"kid":"myRsaPubKey","kty":"RSA","alg":"RSA-2048","keyOps":["encrypt","verify"],"publicKey":"BASE64-ENCODED-PUBLIC-KEY"}},"Full EC key‑pair (ES256)":{"description":"Full EC key‑pair (ES256)","value":{"kid":"myEcKey","kty":"EC","alg":"ES256","keyOps":["sign","verify"],"publicKey":"BASE64-ENCODED-PUBLIC-KEY","privateKey":"BASE64-ENCODED-PRIVATE-KEY"}},"Symmetric AES‑256 key":{"description":"Symmetric AES‑256 key","value":{"kid":"mySymKey","kty":"oct","alg":"AES-256","keyOps":["encrypt","decrypt"],"privateKey":"BASE64-ENCODED-SYMMETRIC-KEY"}}}}},"required":true},"responses":{"201":{"description":"Key imported successfully (new entry).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyExportResponse"},"examples":{"RSA key imported":{"description":"RSA key imported","value":{"kid":"myRsaPubKey","kty":"RSA","alg":"RSA-2048","publicKey":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...","keyOps":["encrypt","verify"],"exportable":true,"createdAt":"2025-01-15T14:30:00Z","expiresAt":"2035-01-15T14:30:00Z","usageCount":0,"maxUsageLimit":100000,"status":"ACTIVE","hash":"A1B2C3D4E5F6789012345678901234567890ABCD"}},"EC key pair imported":{"description":"EC key pair imported","value":{"kid":"myEcKey","kty":"EC","alg":"ES256","publicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...","keyOps":["sign","verify"],"exportable":true,"createdAt":"2025-01-15T14:30:00Z","expiresAt":"2030-01-15T14:30:00Z","usageCount":0,"maxUsageLimit":50000,"status":"ACTIVE","hash":"B2C3D4E5F67890123456789012345678901ABCDE"}},"Symmetric key imported":{"description":"Symmetric key imported","value":{"kid":"mySymKey","kty":"oct","alg":"AES-256","keyOps":["encrypt","decrypt"],"exportable":false,"createdAt":"2025-01-15T14:30:00Z","expiresAt":"2027-01-15T14:30:00Z","usageCount":0,"maxUsageLimit":10000,"status":"ACTIVE","hash":"C3D4E5F678901234567890123456789012ABCDEF"}}}}}},"200":{"description":"Key updated/upgraded successfully (existing entry).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyExportResponse"}}}},"400":{"description":"Invalid input: missing fields, malformed Base64…","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Malformed Base64":{"description":"Malformed Base64","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"'publicKey' is not valid Base64.","instance":"/api/key-management/keys/import","timestamp":1745119700}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"413":{"description":"Payload Too Large: key material exceeds 5 MB.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key too large":{"description":"Key too large","value":{"type":"/errors/payload-too-large","title":"Payload too large","status":413,"detail":"privateKey exceeds the maximum allowed size (5 000 000 bytes).","instance":"/api/key-management/keys/import","timestamp":1745119700}}}}}},"409":{"description":"Conflict: key exists with incompatible data.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Algorithm mismatch":{"description":"Algorithm mismatch","value":{"type":"/errors/conflict","title":"Conflict","status":409,"detail":"Key 'myKey' already exists with algorithm EC-256; requested RSA-2048.","instance":"/api/key-management/keys/import","timestamp":1745119700}}}}}},"500":{"description":"Internal Server Error: unexpected cryptographic/keystore error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/migration/convert-pkcs7-to-jose":{"post":{"tags":["Migration"],"summary":"Convert PKCS#7/CMS to JOSE format","description":"Converts legacy PKCS#7/CMS files to modern JOSE (JWE/JWS) format.\n\nThis is a **format conversion** (PKCS#7 container → JOSE container), not an algorithm conversion.\nClassical algorithms (RSA, ECDSA, AES) are preserved or upgraded (CBC→GCM).\n\n**Supported conversions**:\n\n- SignedData (1 signer) → JWS Compact\n- EnvelopedData (1 recipient) → JWE Compact\n- SignedAndEnvelopedData (1 signer + 1 recipient) → JWE(JWS) Compact\n\n**Future enhancement**: Multi-signer/multi-recipient support with JSON serialization\n\n**Process:**\n1. Parse PKCS#7 structure\n2. Verify signatures (optional)\n3. Decrypt if encrypted (using imported key)\n4. Match signers/recipients with imported keys\n5. Re-sign/re-encrypt with JOSE format\n\n**Prerequisites:** Import private keys via POST /api/migration/pkcs12\n\n**Next steps:** For PQC algorithms, use POST /api/crypto/reencrypt or POST /api/crypto/resign\n","operationId":"convertPkcs7ToJose","requestBody":{"description":"PKCS#7/CMS conversion request with Base64-encoded data and options","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pkcs7ConversionRequest"},"examples":{"SignedData (1 signer, no encryption)":{"summary":"Convert PKCS#7 SignedData to JWS Compact","description":"SignedData with 1 signer. No decryptionKid required. Output: JWS Compact token.","value":{"pkcs7Data":"MIAGCSqGSIb3DQEHA6CAMIACAQAxggE...","serialization":"AUTO","targetFormat":"AUTO","algorithmPolicy":{"allowLegacyHash":false}}},"EnvelopedData (1 recipient, encrypted)":{"summary":"Convert PKCS#7 EnvelopedData to JWE Compact","description":"EnvelopedData with 1 recipient. Requires decryptionKid. Output: JWE Compact token.","value":{"pkcs7Data":"MIIGHgYJKoZIhvcNAQcDoIIGDzCCBgsCAQAxggE...","decryptionKid":"legacy-recipient-key","serialization":"AUTO","targetFormat":"AUTO","algorithmPolicy":{"contentEncryptionUpgrade":"AES_GCM"}}},"SignedAndEnvelopedData (1 signer + 1 recipient)":{"summary":"Convert PKCS#7 SignedAndEnvelopedData to JWE(JWS) Compact","description":"SignedAndEnvelopedData with 1 signer + 1 recipient. Requires decryptionKid. Output: JWE(JWS) Compact nested token.","value":{"pkcs7Data":"MIIHkwYLKoZIhvcNAQkQAQKgggecMIIHmAIBAQ...","decryptionKid":"legacy-recipient-key","serialization":"AUTO","targetFormat":"AUTO","algorithmPolicy":{"allowLegacyHash":false,"contentEncryptionUpgrade":"AES_GCM"}}}}}},"required":true},"responses":{"200":{"description":"PKCS#7 conversion successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pkcs7ConversionResponse"}}}},"400":{"description":"Bad Request: invalid Base64 or malformed PKCS#7","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Unauthorized: missing or invalid JWT token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"413":{"description":"Payload Too Large: decoded PKCS#7 data exceeds 5MB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Unprocessable Entity: conversion not supported or private key missing","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error: unexpected conversion error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/migration/analyze-pkcs7":{"post":{"tags":["Migration"],"summary":"Analyze PKCS#7/CMS file structure","description":"Introspects PKCS#7/CMS binary data and returns structured metadata including\nsigners, recipients, algorithms, certificates, and conversion feasibility.\n\nSupports SignedData, EnvelopedData, and SignedAndEnvelopedData.\nProvides actionable guidance for migration to JOSE (JWE/JWS).\n\n**Current support**: Single signer and single recipient only\n**Multi-actor support**: Planned for future release (multi-signer/multi-recipient with JSON serialization)\n","operationId":"analyzePkcs7","requestBody":{"description":"PKCS#7/CMS analysis request with Base64-encoded DER data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pkcs7AnalysisRequest"},"examples":{"Analyze PKCS#7 SignedData":{"description":"Analyze PKCS#7 SignedData","value":{"pkcs7Data":"MIIGHgYJKoZIhvcNAQcCoIIGDzCCBgsCAQAxggE...","decryptionKid":null,"validateCertificates":false,"validateTimestamp":false}}}}},"required":true},"responses":{"200":{"description":"PKCS#7 analysis successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pkcs7AnalysisResponse"}}}},"400":{"description":"Bad Request: invalid Base64 or malformed PKCS#7","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Unauthorized: missing or invalid JWT token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"413":{"description":"Payload Too Large: decoded PKCS#7 data exceeds 5MB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Unprocessable Entity: valid PKCS#7 but format not supported","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error: unexpected error during analysis","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/key-management/keys":{"get":{"tags":[" Key Management"],"summary":"List all keys (no secret data).","description":" Retrieves a summary list of all keys in the keystore. \n Secret fields (e.g. privateKey) are omitted. Clients can inspect\n usage counts, expiry, status (ACTIVE, EXPIRED, REVOKED…), etc.\n ","operationId":"listAllKeys","responses":{"200":{"description":"Keys listed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListKeysResponse"}}}},"400":{"description":"Invalid input: malformed query parameters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Bearer token missing":{"description":"Bearer token missing","value":{"type":"/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Authentication credentials were not provided.","instance":"/api/key-management/keys","timestamp":1745119900}}}}}},"403":{"description":"Forbidden: authenticated user lacks the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Resource not found: keystore unavailable or missing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"413":{"description":"Payload Too Large: response would exceed server limits.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error: unexpected error while listing keys.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"post":{"tags":[" Key Management"],"summary":"Generate a cryptographic key (classical, symmetric, or post-quantum).","description":"Creates a new key or updates metadata if the public key already exists.\nRefer to GET /api/key-management/supported-algorithms for valid kty/alg.\n","operationId":"generateKey","requestBody":{"description":"Parameters for the key to be generated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyGenerationRequest"},"examples":{"Post‑quantum key (ML‑KEM‑1024)":{"description":"Post‑quantum key (ML‑KEM‑1024)","value":{"kid":"my_MLKEM_Key","kty":"ML-KEM","alg":"ML-KEM-1024","keyOps":["encrypt","decrypt"],"exportable":true,"expiresAt":"2030-05-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","maxUsageLimit":50000,"softUsageLimit":40000}},"Classical RSA key (RSA-4096)":{"description":"Classical RSA key (RSA-4096)","value":{"kid":"my_RSA4096_Key","kty":"RSA","alg":"RSA-4096","keyOps":["encrypt","decrypt","sign","verify"],"exportable":true,"expiresAt":"2030-05-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","maxUsageLimit":20000,"softUsageLimit":18000}},"Classical EC key (ES256)":{"description":"Classical EC key (ES256)","value":{"kid":"myEcKey","kty":"EC","alg":"EC-256","keyOps":["encrypt","decrypt"],"exportable":true,"expiresAt":"2026-01-15T00:00:00Z","maxUsageLimit":5000}},"Post-quantum signing key (ML-DSA)":{"description":"Post-quantum signing key (ML-DSA)","value":{"kid":"myMLDSAKey","kty":"ML-DSA","alg":"ML-DSA-65","keyOps":["sign","verify"],"exportable":true,"expiresAt":"2030-05-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","maxUsageLimit":100000,"softUsageLimit":90000}},"Symmetric key (AES‑256)":{"description":"Symmetric key (AES‑256)","value":{"kid":"mySymKey","kty":"oct","alg":"AES-256","keyOps":["encrypt","decrypt"],"exportable":false}},"Camellia-GCM-256 (Japan/Saudi Arabia/Malaysia CRYPTREC/NCA_NCS)":{"description":"Camellia-GCM-256 (Japan/Saudi Arabia/Malaysia CRYPTREC/NCA_NCS)","value":{"kid":"myCamelliaKey","kty":"oct","alg":"Camellia-GCM-256","keyOps":["encrypt","decrypt"],"exportable":false,"expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000,"softUsageLimit":4000000}},"SM4-GCM-128 (China GM/T mandatory)":{"description":"SM4-GCM-128 (China GM/T mandatory)","value":{"kid":"mySM4Key","kty":"oct","alg":"SM4-GCM-128","keyOps":["encrypt","decrypt"],"exportable":false,"expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000,"softUsageLimit":4000000}},"SM2 signature (China GM/T mandatory)":{"description":"SM2 signature (China GM/T mandatory)","value":{"kid":"mySM2Key","kty":"SM2","alg":"SM2","keyOps":["sign","verify"],"exportable":true,"expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":100000,"softUsageLimit":80000}},"SEED-GCM-128 (Korea KISA mandatory)":{"description":"SEED-GCM-128 (Korea KISA mandatory)","value":{"kid":"mySeedKey","kty":"oct","alg":"SEED-GCM-128","keyOps":["encrypt","decrypt"],"exportable":false,"expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000,"softUsageLimit":4000000}},"ChaCha20-Poly1305 (Malaysia MySEAL/High-performance)":{"description":"ChaCha20-Poly1305 (Malaysia MySEAL/High-performance)","value":{"kid":"myChaChaKey","kty":"oct","alg":"ChaCha20-Poly1305","keyOps":["encrypt","decrypt"],"exportable":false,"expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000,"softUsageLimit":4000000}},"ARIA-GCM-256 (Korea KISA modern cipher)":{"description":"ARIA-GCM-256 (Korea KISA modern cipher)","value":{"kid":"myAriaKey","kty":"oct","alg":"ARIA-GCM-256","keyOps":["encrypt","decrypt"],"exportable":false,"expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000,"softUsageLimit":4000000}},"Falcon-512 (France ANSSI compact PQC signatures)":{"description":"Falcon-512 (France ANSSI compact PQC signatures)","value":{"kid":"myFalconKey","kty":"FALCON","alg":"FALCON-512","keyOps":["sign","verify"],"exportable":true,"expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":100000,"softUsageLimit":80000}}}}},"required":true},"responses":{"201":{"description":"New key created (metadata-only response).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeySummaryResponse"},"examples":{"Post-quantum ML-KEM key created (metadata only)":{"description":"Post-quantum ML-KEM key created (metadata only)","value":{"kid":"my_MLKEM_Key","kty":"ML-KEM","alg":"ML-KEM-1024","keyOps":["encrypt","decrypt"],"exportable":true,"legacy":false,"status":"ACTIVE","createdAt":"2025-01-15T10:20:00Z","expiresAt":"2030-05-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","usageCount":0,"softUsageLimit":40000,"maxUsageLimit":50000,"hash":"D4E5F6789012345678901234567890ABCDEF0123","nextKid":null,"previousKid":null}},"Classical RSA-4096 key created (metadata only)":{"description":"Classical RSA-4096 key created (metadata only)","value":{"kid":"my_RSA4096_Key","kty":"RSA","alg":"RSA-4096","keyOps":["encrypt","decrypt","sign","verify"],"exportable":true,"legacy":false,"status":"ACTIVE","createdAt":"2025-01-15T10:20:00Z","expiresAt":"2030-05-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","usageCount":0,"softUsageLimit":18000,"maxUsageLimit":20000,"hash":"E5F67890123456789012345678901ABCDEF01234","nextKid":null,"previousKid":null}},"EC-256 key created":{"description":"EC-256 key created","value":{"kid":"myEcKey","kty":"EC","alg":"EC-256","publicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...","keyOps":["encrypt","decrypt"],"exportable":true,"createdAt":"2025-01-15T10:20:00Z","expiresAt":"2026-01-15T00:00:00Z","usageCount":0,"lastUsedAt":null,"maxUsageLimit":5000,"softUsageLimit":5000,"status":"ACTIVE","hash":"F678901234567890123456789012ABCDEF012345"}},"ML-DSA-65 signing key created":{"description":"ML-DSA-65 signing key created","value":{"kid":"myMLDSAKey","kty":"ML-DSA","alg":"ML-DSA-65","publicKey":"BASE64-ENCODED-ML-DSA-PUBLIC-KEY","keyOps":["sign","verify"],"exportable":true,"createdAt":"2025-01-15T10:20:00Z","expiresAt":"2030-05-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","usageCount":0,"lastUsedAt":null,"softUsageLimit":90000,"maxUsageLimit":100000,"status":"ACTIVE","hash":"78901234567890123456789012ABCDEF01234567"}},"AES-256 symmetric key created (metadata only)":{"description":"AES-256 symmetric key created (metadata only)","value":{"kid":"mySymKey","kty":"oct","alg":"AES-256","keyOps":["encrypt","decrypt"],"exportable":false,"legacy":false,"status":"ACTIVE","createdAt":"2025-01-15T10:20:00Z","expiresAt":"2125-01-15T10:20:00Z","usageCount":0,"maxUsageLimit":0,"hash":"890123456789012345678901ABCDEF0123456789","nextKid":null,"previousKid":null}},"Camellia-GCM-256 key created (Japan/Saudi Arabia)":{"description":"Camellia-GCM-256 key created (Japan/Saudi Arabia)","value":{"kid":"myCamelliaKey","kty":"oct","alg":"Camellia-GCM-256","keyOps":["encrypt","decrypt"],"exportable":false,"createdAt":"2025-01-15T10:20:00Z","expiresAt":"2030-12-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","usageCount":0,"lastUsedAt":null,"maxUsageLimit":5000000,"softUsageLimit":4000000,"status":"ACTIVE","hash":"ABC123456789012345678901234567890ABCDEF01"}},"SM4-GCM-128 key created (China GM/T)":{"description":"SM4-GCM-128 key created (China GM/T)","value":{"kid":"mySM4Key","kty":"oct","alg":"SM4-GCM-128","keyOps":["encrypt","decrypt"],"exportable":false,"createdAt":"2025-01-15T10:20:00Z","expiresAt":"2030-12-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","usageCount":0,"lastUsedAt":null,"maxUsageLimit":5000000,"softUsageLimit":4000000,"status":"ACTIVE","hash":"DEF456789012345678901234567890ABCDEF01234"}},"SM2 signature key created (China GM/T)":{"description":"SM2 signature key created (China GM/T)","value":{"kid":"mySM2Key","kty":"SM2","alg":"SM2","publicKey":"BASE64-ENCODED-SM2-PUBLIC-KEY","keyOps":["sign","verify"],"exportable":true,"createdAt":"2025-01-15T10:20:00Z","expiresAt":"2030-12-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","usageCount":0,"lastUsedAt":null,"maxUsageLimit":100000,"softUsageLimit":80000,"status":"ACTIVE","hash":"FED789012345678901234567890ABCDEF0123456"}},"SEED-GCM-128 key created (Korea KISA)":{"description":"SEED-GCM-128 key created (Korea KISA)","value":{"kid":"mySeedKey","kty":"oct","alg":"SEED-GCM-128","keyOps":["encrypt","decrypt"],"exportable":false,"createdAt":"2025-01-15T10:20:00Z","expiresAt":"2030-12-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","usageCount":0,"lastUsedAt":null,"maxUsageLimit":5000000,"softUsageLimit":4000000,"status":"ACTIVE","hash":"CBA987654321098765432109876543210FEDCBA98"}},"ChaCha20-Poly1305 key created (Malaysia MySEAL)":{"description":"ChaCha20-Poly1305 key created (Malaysia MySEAL)","value":{"kid":"myChaChaKey","kty":"oct","alg":"ChaCha20-Poly1305","keyOps":["encrypt","decrypt"],"exportable":false,"createdAt":"2025-01-15T10:20:00Z","expiresAt":"2030-12-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","usageCount":0,"lastUsedAt":null,"maxUsageLimit":5000000,"softUsageLimit":4000000,"status":"ACTIVE","hash":"987654321098765432109876543210FEDCBA9876"}},"ARIA-GCM-256 key created (Korea KISA)":{"description":"ARIA-GCM-256 key created (Korea KISA)","value":{"kid":"myAriaKey","kty":"oct","alg":"ARIA-GCM-256","keyOps":["encrypt","decrypt"],"exportable":false,"createdAt":"2025-01-15T10:20:00Z","expiresAt":"2030-12-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","usageCount":0,"lastUsedAt":null,"maxUsageLimit":5000000,"softUsageLimit":4000000,"status":"ACTIVE","hash":"ARIA123456789012345678901234567890ABCDEF0"}},"Falcon-512 key created (France ANSSI)":{"description":"Falcon-512 key created (France ANSSI)","value":{"kid":"myFalconKey","kty":"FALCON","alg":"FALCON-512","publicKey":"BASE64-ENCODED-FALCON-PUBLIC-KEY","keyOps":["sign","verify"],"exportable":true,"createdAt":"2025-01-15T10:20:00Z","expiresAt":"2030-12-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","usageCount":0,"lastUsedAt":null,"maxUsageLimit":100000,"softUsageLimit":80000,"status":"ACTIVE","hash":"123456789ABCDEF0123456789ABCDEF012345678"}}}}}},"200":{"description":"Existing key metadata updated (same public key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyExportResponse"},"examples":{"Metadata updated for existing key":{"description":"Metadata updated for existing key","value":{"kid":"myExistingKey","kty":"RSA","alg":"RSA-2048","publicKey":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...","keyOps":["encrypt","decrypt","sign","verify"],"exportable":true,"createdAt":"2025-01-10T10:20:00Z","updatedAt":"2025-01-16T14:30:00Z","expiresAt":"2030-05-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","usageCount":150,"lastUsedAt":"2025-01-16T14:25:00Z","maxUsageLimit":50000,"softUsageLimit":40000,"status":"ACTIVE","hash":"ABCDEF0123456789ABCDEF0123456789ABCDEF01"}}}}}},"400":{"description":"Invalid input: missing or malformed fields.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Missing kid":{"description":"Missing kid","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"'kid' must not be blank.","instance":"/api/key-management/keys","timestamp":1745119500}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Forbidden: authenticated user lacks the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Conflict: key collision or key in an invalid state.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key exists with different algorithm":{"description":"Key exists with different algorithm","value":{"type":"/errors/conflict","title":"Conflict","status":409,"detail":"Key 'myKey' already exists with algorithm RSA-2048; requested EC-256.","instance":"/api/key-management/keys","timestamp":1745119500}},"Key in invalid state":{"description":"Key in invalid state","value":{"type":"/errors/invalid-key-state","title":"Conflict","status":409,"detail":"Key 'myKey' is disabled and cannot be updated.","instance":"/api/key-management/keys","timestamp":1745119500}}}}}},"413":{"description":"Payload Too Large: one or more parameters exceed limits.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Public key too large":{"description":"Public key too large","value":{"type":"/errors/payload-too-large","title":"Payload too large","status":413,"detail":"Parameter 'publicKey' exceeds the maximum allowed size (5 000 000 bytes).","instance":"/api/key-management/keys","timestamp":1745119500}}}}}},"500":{"description":"Internal Server Error: unexpected cryptographic/keystore error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/key-management/keys/{kid}/rotations":{"post":{"tags":[" Key Management"],"summary":"Rotate a key immediately.","description":"Creates a successor key and atomically replaces {kid}.\nThe request body contains a single field newKey with\nthe same schema accepted by POST /keys.\nOn success the endpoint replies with 200 OK and the\nnewly-created key. Deferred (scheduled) rotations are not\nsupported in this API version.","operationId":"createRotation","parameters":[{"name":"kid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"JSON body containing the successor-key specification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotationRequest"},"examples":{"EC-256 rotation request":{"description":"EC-256 rotation request","value":{"newKey":{"kid":"myEcKey-20250629","kty":"EC","alg":"EC-256","keyOps":["sign","verify"],"exportable":true}}},"RSA-4096 rotation request":{"description":"RSA-4096 rotation request","value":{"newKey":{"kid":"myRsaKey-20250629","kty":"RSA","alg":"RSA-4096","keyOps":["encrypt","decrypt","sign","verify"],"exportable":true}}},"ML-KEM-1024 rotation request":{"description":"ML-KEM-1024 rotation request","value":{"newKey":{"kid":"myMlKemKey-20250629","kty":"ML-KEM","alg":"ML-KEM-1024","keyOps":["encrypt","decrypt"],"exportable":true}}},"ML-DSA-65 rotation request":{"description":"ML-DSA-65 rotation request","value":{"newKey":{"kid":"myMlDsaKey-20250629","kty":"ML-DSA","alg":"ML-DSA-65","keyOps":["sign","verify"],"exportable":true}}},"AES-256 rotation request":{"description":"AES-256 rotation request","value":{"newKey":{"kid":"mySymKey-20250629","kty":"oct","alg":"AES-256","keyOps":["encrypt","decrypt"],"exportable":false}}},"Camellia-GCM-256 rotation (Japan/Saudi Arabia)":{"description":"Camellia-GCM-256 rotation (Japan/Saudi Arabia)","value":{"newKey":{"kid":"myCamelliaKey-20250629","kty":"oct","alg":"Camellia-GCM-256","keyOps":["encrypt","decrypt"],"exportable":false,"expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000}}},"SM4-GCM-128 rotation (China GM/T)":{"description":"SM4-GCM-128 rotation (China GM/T)","value":{"newKey":{"kid":"mySM4Key-20250629","kty":"oct","alg":"SM4-GCM-128","keyOps":["encrypt","decrypt"],"exportable":false,"expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000}}},"SM2 rotation (China GM/T signature)":{"description":"SM2 rotation (China GM/T signature)","value":{"newKey":{"kid":"mySM2Key-20250629","kty":"SM2","alg":"SM2","keyOps":["sign","verify"],"exportable":true,"expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":100000}}},"SEED-GCM-128 rotation (Korea KISA)":{"description":"SEED-GCM-128 rotation (Korea KISA)","value":{"newKey":{"kid":"mySeedKey-20250629","kty":"oct","alg":"SEED-GCM-128","keyOps":["encrypt","decrypt"],"exportable":false,"expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000}}},"ChaCha20-Poly1305 rotation (Malaysia MySEAL)":{"description":"ChaCha20-Poly1305 rotation (Malaysia MySEAL)","value":{"newKey":{"kid":"myChaChaKey-20250629","kty":"oct","alg":"ChaCha20-Poly1305","keyOps":["encrypt","decrypt"],"exportable":false,"expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000}}},"Falcon-512 rotation (France ANSSI)":{"description":"Falcon-512 rotation (France ANSSI)","value":{"newKey":{"kid":"myFalconKey-20250629","kty":"FALCON","alg":"FALCON-512","keyOps":["sign","verify"],"exportable":true,"expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":100000}}}}}},"required":true},"responses":{"200":{"description":"Rotation executed; the successor key is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyExportResponse"},"examples":{"EC-256 rotation response":{"description":"EC-256 rotation response","value":{"kid":"myEcKey-20250629","kty":"EC","alg":"EC-256","publicKey":"BASE64-PUBKEY","keyOps":["sign","verify"],"exportable":true,"createdAt":"2025-06-29T12:00:00Z","status":"ACTIVE","previousKid":"myEcKey"}},"RSA-4096 rotation response":{"description":"RSA-4096 rotation response","value":{"kid":"myRsaKey-20250629","kty":"RSA","alg":"RSA-4096","publicKey":"BASE64-PUBKEY","keyOps":["encrypt","decrypt","sign","verify"],"exportable":true,"createdAt":"2025-06-29T12:00:00Z","status":"ACTIVE","previousKid":"myRsaKey"}},"ML-KEM-1024 rotation response":{"description":"ML-KEM-1024 rotation response","value":{"kid":"myMlKemKey-20250629","kty":"ML-KEM","alg":"ML-KEM-1024","publicKey":"BASE64-PUBKEY","keyOps":["encrypt","decrypt"],"exportable":true,"createdAt":"2025-06-29T12:00:00Z","status":"ACTIVE","previousKid":"myMlKemKey"}},"ML-DSA-65 rotation response":{"description":"ML-DSA-65 rotation response","value":{"kid":"myMlDsaKey-20250629","kty":"ML-DSA","alg":"ML-DSA-65","publicKey":"BASE64-PUBKEY","keyOps":["sign","verify"],"exportable":true,"createdAt":"2025-06-29T12:00:00Z","status":"ACTIVE","previousKid":"myMlDsaKey"}},"AES-256 rotation response":{"description":"AES-256 rotation response","value":{"kid":"mySymKey-20250629","kty":"oct","alg":"AES-256","keyOps":["encrypt","decrypt"],"exportable":false,"createdAt":"2025-06-29T12:00:00Z","status":"ACTIVE","previousKid":"mySymKey"}},"Camellia-GCM-256 rotation response (Japan/Saudi Arabia)":{"description":"Camellia-GCM-256 rotation response (Japan/Saudi Arabia)","value":{"kid":"myCamelliaKey-20250629","kty":"oct","alg":"Camellia-GCM-256","keyOps":["encrypt","decrypt"],"exportable":false,"createdAt":"2025-06-29T12:00:00Z","expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000,"usageCount":0,"status":"ACTIVE","previousKid":"myCamelliaKey"}},"SM4-GCM-128 rotation response (China GM/T)":{"description":"SM4-GCM-128 rotation response (China GM/T)","value":{"kid":"mySM4Key-20250629","kty":"oct","alg":"SM4-GCM-128","keyOps":["encrypt","decrypt"],"exportable":false,"createdAt":"2025-06-29T12:00:00Z","expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000,"usageCount":0,"status":"ACTIVE","previousKid":"mySM4Key"}},"SM2 rotation response (China GM/T signature)":{"description":"SM2 rotation response (China GM/T signature)","value":{"kid":"mySM2Key-20250629","kty":"SM2","alg":"SM2","publicKey":"BASE64-ENCODED-SM2-PUBLIC-KEY","keyOps":["sign","verify"],"exportable":true,"createdAt":"2025-06-29T12:00:00Z","expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":100000,"usageCount":0,"status":"ACTIVE","previousKid":"mySM2Key"}},"SEED-GCM-128 rotation response (Korea KISA)":{"description":"SEED-GCM-128 rotation response (Korea KISA)","value":{"kid":"mySeedKey-20250629","kty":"oct","alg":"SEED-GCM-128","keyOps":["encrypt","decrypt"],"exportable":false,"createdAt":"2025-06-29T12:00:00Z","expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000,"usageCount":0,"status":"ACTIVE","previousKid":"mySeedKey"}},"ChaCha20-Poly1305 rotation response (Malaysia MySEAL)":{"description":"ChaCha20-Poly1305 rotation response (Malaysia MySEAL)","value":{"kid":"myChaChaKey-20250629","kty":"oct","alg":"ChaCha20-Poly1305","keyOps":["encrypt","decrypt"],"exportable":false,"createdAt":"2025-06-29T12:00:00Z","expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000,"usageCount":0,"status":"ACTIVE","previousKid":"myChaChaKey"}},"ARIA-GCM-256 rotation response (Korea KISA)":{"description":"ARIA-GCM-256 rotation response (Korea KISA)","value":{"kid":"myAriaKey-20250629","kty":"oct","alg":"ARIA-GCM-256","keyOps":["encrypt","decrypt"],"exportable":false,"createdAt":"2025-06-29T12:00:00Z","expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":5000000,"usageCount":0,"status":"ACTIVE","previousKid":"myAriaKey"}},"Falcon-512 rotation response (France ANSSI)":{"description":"Falcon-512 rotation response (France ANSSI)","value":{"kid":"myFalconKey-20250629","kty":"FALCON","alg":"FALCON-512","publicKey":"BASE64-ENCODED-FALCON-PUBLIC-KEY","keyOps":["sign","verify"],"exportable":true,"createdAt":"2025-06-29T12:00:00Z","expiresAt":"2030-12-31T23:59:59Z","maxUsageLimit":100000,"usageCount":0,"status":"ACTIVE","previousKid":"myFalconKey"}}}}}},"400":{"description":"Invalid input: missing field newKey or malformed payload.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Missing newKey":{"description":"Missing newKey","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"'newKey' must not be null.","instance":"/api/key-management/keys/myKey/rotations","timestamp":1745121100}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Forbidden: authenticated user lacks the required scope or key policy denies rotation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Key not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Unknown kid":{"description":"Unknown kid","value":{"type":"/errors/not-found","title":"Resource not found","status":404,"detail":"Key 'nonexistentKey' does not exist.","instance":"/api/key-management/keys/nonexistentKey/rotations","timestamp":1745121150}}}}}},"409":{"description":"Conflict: key is in an invalid state (e.g., already revoked or archived).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key in invalid state":{"description":"Key in invalid state","value":{"type":"/errors/invalid-key-state","title":"Conflict","status":409,"detail":"Key 'myKey' is revoked and cannot be rotated.","instance":"/api/key-management/keys/myKey/rotations","timestamp":1745121200}}}}}},"413":{"description":"Payload Too Large: successor key parameters exceed limits.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Public key too large":{"description":"Public key too large","value":{"type":"/errors/payload-too-large","title":"Payload too large","status":413,"detail":"Parameter 'publicKey' exceeds the maximum allowed size (5 000 000 bytes).","instance":"/api/key-management/keys/myKey/rotations","timestamp":1745121250}}}}}},"500":{"description":"Internal Server Error: unexpected cryptographic or keystore failure.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/key-management/keys/{kid}/actions/revoke":{"post":{"tags":[" Key Management"],"summary":"Revoke a key by kid.","description":"Changes the key's status to REVOKED. The operation\ncannot be undone and the key becomes cryptographically unusable.\n","operationId":"revokeKey","parameters":[{"name":"kid","in":"path","description":"Identifier of the key to revoke.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Key revoked successfully (no content)."},"400":{"description":"Invalid input: missing or malformed parameters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Missing kid":{"description":"Missing kid","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"'kid' must not be blank.","instance":"/api/key-management/keys//actions/revoke","timestamp":1745120600}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Forbidden: authenticated user lacks the required scope or operation not allowed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Key not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Unknown kid":{"description":"Unknown kid","value":{"type":"/errors/not-found","title":"Resource not found","status":404,"detail":"Key 'nonexistentKey' does not exist.","instance":"/api/key-management/keys/nonexistentKey/actions/revoke","timestamp":1745120200}}}}}},"409":{"description":"Conflict: key is in an invalid state (e.g., already revoked).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key already revoked":{"description":"Key already revoked","value":{"type":"/errors/invalid-key-state","title":"Conflict","status":409,"detail":"Key 'myKey' is already revoked and cannot be revoked again.","instance":"/api/key-management/keys/myKey/actions/revoke","timestamp":1745120650}}}}}},"500":{"description":"Internal Server Error: unexpected error while revoking the key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/key-management/composite-keys":{"post":{"tags":["Key Management"," Key Management"],"summary":"Generate composite hybrid key","description":"Generates a composite hybrid key combining classical and post-quantum cryptographic algorithms for quantum-resistant security following NIST CSWP 39 recommendations.\n\n## Composite Modes\n\n| Mode | Purpose | Key Operations | Use Case |\n|------|---------|----------------|----------|\n| HYBRID_KEM_COMBINE | Hybrid key encapsulation | encrypt, decrypt | Secure key exchange, data encryption |\n| DUALSIGN | Dual digital signatures | sign, verify | Document signing, authentication |\n\n## Valid Algorithm Combinations\n\n### HYBRID_KEM_COMBINE (AND-decrypt semantics)\nBoth classical and PQC secrets are combined via HKDF. Decryption requires BOTH components, providing security even if one algorithm is compromised.\n\n| Classical | PQC | NIST Level | Recommendation |\n|-----------|-----|------------|----------------|\n| X25519 | ML-KEM-768 | 3 | **Recommended** - Best performance/security balance |\n| X25519 | ML-KEM-1024 | 5 | High security, larger ciphertext |\n| RSA-3072 | ML-KEM-768 | 3 | Legacy system compatibility |\n| RSA-4096 | ML-KEM-1024 | 5 | Maximum security, largest overhead |\n\n### DUALSIGN (Dual signature semantics)\nGenerates two independent signatures (classical + PQC). Verification policy determines which signatures must verify.\n\n| Classical | PQC | NIST Level | Recommendation |\n|-----------|-----|------------|----------------|\n| Ed25519 | ML-DSA-65 | 3 | **Recommended** - Best performance |\n| Ed25519 | ML-DSA-44 | 1 | Fast signing, smaller signatures |\n| ECDSA-P256 | ML-DSA-65 | 3 | FIPS 186-5 compatible |\n| ECDSA-P256 | ML-DSA-44 | 1 | FIPS compatible, smaller signatures |\n| ECDSA-P384 | ML-DSA-87 | 5 | Maximum security DUALSIGN |\n\n## Verification Policies (DUALSIGN only)\n\n| Policy | Behavior | Use Case |\n|--------|----------|----------|\n| ALL | Both signatures must verify | Strictest, recommended for high-security |\n| ANY | At least one must verify | Graceful degradation during transition |\n| CLASSICAL_REQUIRED | Classical required, PQC optional | Classical systems still trusted |\n| PQC_REQUIRED | PQC required, classical optional | Prioritize quantum resistance |\n\n## Compliance\n\n- **NIST CSWP 39 §3.2.4**: Hybrid algorithm construction\n- **GSA PQC Buyer's Guide §6.3**: HNDR (Harvest Now, Decrypt Later) mitigation\n- **NIST SP 800-227**: Hybrid KEM recommendations\n- **FIPS 186-5**: Classical signature algorithm compliance\n","operationId":"generateCompositeKey","requestBody":{"description":"Composite key generation request specifying mode, algorithms, and optional limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompositeKeyRequest"},"examples":{"1. X25519+ML-KEM-768 (Recommended)":{"summary":"HYBRID_KEM_COMBINE - Best balance of performance and security","description":"Recommended configuration for hybrid KEM. X25519 provides efficient classical key exchange, ML-KEM-768 adds quantum resistance at NIST Level 3.","value":{"kid":"hybrid-kem-recommended","mode":"HYBRID_KEM_COMBINE","componentAlgorithms":[{"role":"classical","algorithm":"X25519"},{"role":"pqc","algorithm":"ML-KEM-768"}],"kdf":"HKDF-SHA256","maxUsageLimit":1000000,"exportable":true}},"2. X25519+ML-KEM-1024 (High Security)":{"summary":"HYBRID_KEM_COMBINE - Maximum quantum security with X25519","description":"High security configuration using ML-KEM-1024 (NIST Level 5). Larger ciphertext but stronger protection against future quantum computers.","value":{"kid":"hybrid-kem-high-security","mode":"HYBRID_KEM_COMBINE","componentAlgorithms":[{"role":"classical","algorithm":"X25519"},{"role":"pqc","algorithm":"ML-KEM-1024"}],"kdf":"HKDF-SHA256","expiresAt":"2035-12-31T23:59:59Z","maxUsageLimit":500000}},"3. RSA-3072+ML-KEM-768 (Legacy Compatible)":{"summary":"HYBRID_KEM_COMBINE - For systems requiring RSA compatibility","description":"Legacy-compatible configuration using RSA-3072. Use when interoperability with existing RSA infrastructure is required.","value":{"kid":"hybrid-kem-legacy-rsa","mode":"HYBRID_KEM_COMBINE","componentAlgorithms":[{"role":"classical","algorithm":"RSA-3072"},{"role":"pqc","algorithm":"ML-KEM-768"}],"kdf":"HKDF-SHA256","keyOps":["encrypt","decrypt"],"exportable":false}},"4. RSA-4096+ML-KEM-1024 (Maximum Security)":{"summary":"HYBRID_KEM_COMBINE - Highest security level for long-term protection","description":"Maximum security configuration at NIST Level 5. Use for data requiring protection beyond 2040. Largest key sizes and ciphertext.","value":{"kid":"hybrid-kem-maximum","mode":"HYBRID_KEM_COMBINE","componentAlgorithms":[{"role":"classical","algorithm":"RSA-4096"},{"role":"pqc","algorithm":"ML-KEM-1024"}],"kdf":"HKDF-SHA256","expiresAt":"2040-12-31T23:59:59Z","softLimitExpiration":"2039-01-01T00:00:00Z","maxUsageLimit":100000,"softUsageLimit":80000}},"5. Ed25519+ML-DSA-65 (Recommended DUALSIGN)":{"summary":"DUALSIGN - Best performance for dual signatures","description":"Recommended configuration for dual signatures. Ed25519 provides fast classical signatures, ML-DSA-65 adds quantum resistance at NIST Level 3.","value":{"kid":"dualsign-recommended","mode":"DUALSIGN","componentAlgorithms":[{"role":"classical","algorithm":"Ed25519"},{"role":"pqc","algorithm":"ML-DSA-65"}],"verificationPolicy":"ALL","maxUsageLimit":500000,"expiresAt":"2030-12-31T23:59:59Z"}},"6. Ed25519+ML-DSA-44 (Fast Signing)":{"summary":"DUALSIGN - Optimized for signature speed","description":"Faster signing configuration using ML-DSA-44 (NIST Level 1). Smaller signatures, suitable for high-throughput scenarios.","value":{"kid":"dualsign-fast","mode":"DUALSIGN","componentAlgorithms":[{"role":"classical","algorithm":"Ed25519"},{"role":"pqc","algorithm":"ML-DSA-44"}],"verificationPolicy":"ANY","keyOps":["sign","verify"]}},"7. ECDSA-P256+ML-DSA-65 (FIPS Compatible)":{"summary":"DUALSIGN - FIPS 186-5 compliant classical component","description":"FIPS-compatible configuration using ECDSA-P256. Required for federal government and regulated industries requiring FIPS compliance.","value":{"kid":"dualsign-fips","mode":"DUALSIGN","componentAlgorithms":[{"role":"classical","algorithm":"ECDSA-P256"},{"role":"pqc","algorithm":"ML-DSA-65"}],"verificationPolicy":"CLASSICAL_REQUIRED","expiresAt":"2028-12-31T23:59:59Z","exportable":true}},"8. ECDSA-P384+ML-DSA-87 (High Security DUALSIGN)":{"summary":"DUALSIGN - Maximum security for signatures","description":"Highest security DUALSIGN configuration at NIST Level 5. Use for critical document signing requiring long-term validity.","value":{"kid":"dualsign-high-security","mode":"DUALSIGN","componentAlgorithms":[{"role":"classical","algorithm":"ECDSA-P384"},{"role":"pqc","algorithm":"ML-DSA-87"}],"verificationPolicy":"PQC_REQUIRED","expiresAt":"2040-12-31T23:59:59Z","maxUsageLimit":100000}},"9. DUALSIGN Full Configuration":{"summary":"DUALSIGN with all optional fields demonstrated","description":"Complete example showing all available configuration options for DUALSIGN mode including soft limits for proactive key rotation.","value":{"kid":"dualsign-full-options","mode":"DUALSIGN","componentAlgorithms":[{"role":"classical","algorithm":"Ed25519"},{"role":"pqc","algorithm":"ML-DSA-65"}],"verificationPolicy":"ALL","keyOps":["sign","verify"],"expiresAt":"2030-12-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","maxUsageLimit":100000,"softUsageLimit":80000,"exportable":false}}}}},"required":true},"responses":{"201":{"description":"Composite key created successfully. Returns key metadata without cryptographic material.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeySummaryResponse"},"examples":{"HYBRID_KEM_COMBINE key created":{"summary":"X25519+ML-KEM-768 composite key","description":"HYBRID_KEM_COMBINE key created","value":{"kid":"hybrid-kem-recommended","type":"COMPOSITE","compositeMode":"HYBRID_KEM_COMBINE","alg":"X25519+ML-KEM-768","keyOps":["encrypt","decrypt"],"exportable":true,"legacy":false,"status":"ACTIVE","createdAt":"2025-12-27T10:00:00Z","usageCount":0,"maxUsageLimit":1000000}},"HYBRID_KEM_COMBINE with limits":{"summary":"RSA-4096+ML-KEM-1024 with soft/hard limits","description":"HYBRID_KEM_COMBINE with limits","value":{"kid":"hybrid-kem-maximum","type":"COMPOSITE","compositeMode":"HYBRID_KEM_COMBINE","alg":"RSA-4096+ML-KEM-1024","keyOps":["encrypt","decrypt"],"exportable":false,"legacy":false,"status":"ACTIVE","createdAt":"2025-12-27T10:00:00Z","expiresAt":"2040-12-31T23:59:59Z","softLimitExpiration":"2039-01-01T00:00:00Z","usageCount":0,"softUsageLimit":80000,"maxUsageLimit":100000}},"DUALSIGN key created":{"summary":"Ed25519+ML-DSA-65 dual signature key","description":"DUALSIGN key created","value":{"kid":"dualsign-recommended","type":"COMPOSITE","compositeMode":"DUALSIGN","alg":"Ed25519+ML-DSA-65","keyOps":["sign","verify"],"exportable":false,"legacy":false,"status":"ACTIVE","createdAt":"2025-12-27T10:00:00Z","expiresAt":"2030-12-31T23:59:59Z","usageCount":0,"maxUsageLimit":500000}},"DUALSIGN with full options":{"summary":"Complete DUALSIGN key with all limits configured","description":"DUALSIGN with full options","value":{"kid":"dualsign-full-options","type":"COMPOSITE","compositeMode":"DUALSIGN","alg":"Ed25519+ML-DSA-65","keyOps":["sign","verify"],"exportable":false,"legacy":false,"status":"ACTIVE","createdAt":"2025-12-27T10:00:00Z","expiresAt":"2030-12-31T23:59:59Z","softLimitExpiration":"2029-12-31T23:59:59Z","usageCount":0,"softUsageLimit":80000,"maxUsageLimit":100000}}}}}},"400":{"description":"Invalid request - validation failed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Missing required field":{"summary":"kid is required","description":"Missing required field","value":{"type":"/errors/validation","title":"Validation failed","status":400,"detail":"kid is required","instance":"/api/key-management/composite-keys"}},"Invalid algorithm for mode":{"summary":"Using signature algorithm with HYBRID_KEM_COMBINE","description":"Invalid algorithm for mode","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"Classical component must be X25519 or RSA for HYBRID_KEM_COMBINE: Ed25519","instance":"/api/key-management/composite-keys"}},"Security level mismatch":{"summary":"Incompatible security levels between algorithms","description":"Security level mismatch","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"Security level mismatch: X25519 (level 1) + ML-KEM-1024 (level 5). Levels must be within 1 step of each other.","instance":"/api/key-management/composite-keys"}},"Invalid PQC algorithm":{"summary":"Using KEM algorithm with DUALSIGN mode","description":"Invalid PQC algorithm","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"PQC component must be ML-DSA variant for DUALSIGN: ML-KEM-768","instance":"/api/key-management/composite-keys"}}}}}},"401":{"description":"Authentication required - missing or invalid Bearer token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Missing token":{"description":"Missing token","value":{"type":"/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Full authentication is required to access this resource","instance":"/api/key-management/composite-keys"}}}}}},"403":{"description":"Insufficient permissions - missing key_management.generateKey scope","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Missing scope":{"description":"Missing scope","value":{"type":"/errors/forbidden","title":"Forbidden","status":403,"detail":"Access denied. Required scope: key_management.generateKey","instance":"/api/key-management/composite-keys"}}}}}},"409":{"description":"Key with same KID already exists in tenant keystore","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Duplicate kid":{"summary":"Key identifier already in use","description":"Duplicate kid","value":{"type":"/errors/resource-conflict","title":"Resource conflict","status":409,"detail":"Key with kid 'hybrid-kem-recommended' already exists","instance":"/api/key-management/composite-keys"}},"Mode conflict":{"summary":"Existing key has different mode","description":"Mode conflict","value":{"type":"/errors/resource-conflict","title":"Resource conflict","status":409,"detail":"Key 'hybrid-kem-001' exists with different mode: DUALSIGN (requested: HYBRID_KEM_COMBINE)","instance":"/api/key-management/composite-keys"}}}}}},"413":{"description":"Request payload too large - kid exceeds maximum length","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Kid too long":{"description":"Kid too long","value":{"type":"/errors/payload-too-large","title":"Payload too large","status":413,"detail":"Key identifier exceeds maximum length of 256 characters","instance":"/api/key-management/composite-keys"}}}}}},"500":{"description":"Internal server error - keystore or cryptographic operation failure","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Keystore error":{"description":"Keystore error","value":{"type":"/errors/internal","title":"Internal server error","status":500,"detail":"Failed to generate composite key: keystore operation failed","instance":"/api/key-management/composite-keys"}}}}}}}}},"/api/interoperability/verify":{"post":{"tags":["Interoperability"],"summary":"Verify a detached General-JSON JWS with a supplied public key (stream).","description":"Accepts two multipart parts:\n• metadata – JSON (SignatureUtilityApi)\n containing the caller's detached-JWS object (signatureBase64)\n and the corresponding publicKey.\n• file – the raw payload that was signed.\n\nThe controller ignores any kid inside the JWS header\nand uses the public key supplied by the caller for streaming\nverification. On success the endpoint returns a\nVerifySignatureResponse with isValid=true.\n","operationId":"verify","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/SignatureUtilityApi"},"file":{"type":"string","format":"binary","description":"Raw payload that was originally signed"}},"required":["file","metadata"]}}}},"responses":{"200":{"description":"Signature verified; JSON result returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifySignatureResponse"},"examples":{"Valid signature":{"description":"Valid signature","value":{"isValid":true,"keyRequested":"utilityPublicKey","actualKeyUsed":"utilityPublicKey","algorithmUsed":"ML-DSA-87","warnings":[]}}}}}},"400":{"description":"Invalid key, JWS, or algorithm.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Malformed Base64":{"description":"Malformed Base64","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"'publicKey' is not valid Base64.","instance":"/api/interoperability/verify","timestamp":1745121200}}}}}},"401":{"description":"Unauthorized – missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"413":{"description":"Payload Too Large – file or metadata > 5 MiB.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error – unexpected verification failure.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/interoperability/encrypt":{"post":{"tags":["Interoperability"],"summary":"Encrypt data with a provided public key (stream).","description":"Accepts two multipart parts:\n• metadata – JSON (CryptoUtilityApi) with\n kty, alg, publicKey\n• file – binary plaintext\nReturns a streaming application/octet-stream response\nwithout persisting the key.\n","operationId":"encrypt","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/CryptoUtilityApi"},"file":{"type":"string","format":"binary","description":"Plaintext file (binary)."}},"required":["file","metadata"]},"encoding":{"metadata":{"contentType":"application/json"}}}}},"responses":{"200":{"description":"Plaintext encrypted successfully (stream).","content":{"application/octet-stream":{}}},"400":{"description":"Invalid key material or malformed multipart.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Missing publicKey":{"description":"Missing publicKey","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"'publicKey' field is required.","instance":"/api/interoperability/encrypt","timestamp":1745120900}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"413":{"description":"Payload Too Large: plaintext > 5 MB.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error: unexpected error during utility encryption.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/crypto/verify":{"post":{"tags":[" Secure"],"summary":"Verify a Compact JWS signature","description":"Accepts a single-field JSON payload containing a Compact JWS string.\nExtracts the kid and signature algorithm from the protected header,\nverifies the signature, and returns the Base64-encoded payload plus key metadata.\n","operationId":"verifySignature","requestBody":{"description":"JSON object with one field: the Compact JWS to verify.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyJwsRequest"},"examples":{"VerifyJwsRequest":{"description":"VerifyJwsRequest","value":{"jws":"eyJhbGciOiJSUzI1NiIsImtpZCI6Im15S2V5S2lkIn0.UGF5bG9hZA.ZXlKaGJHY2lPaUpJVXpJMU5pSjku..."}}}}},"required":true},"responses":{"200":{"description":"Signature verification completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifySignatureResponse"},"examples":{"Valid signature":{"description":"Valid signature","value":{"payload":"SGVsbG8gQW5rYQ==","keyRequested":"myVerifyKeyKid","actualKeyUsed":"myVerifyKeyKid_v2","algorithmUsed":"Falcon-512","warnings":[]}}}}}},"400":{"description":"Bad Request: malformed JWS or missing jws field.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid input":{"description":"Invalid input","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"JWS string is not valid Base64 or missing.","instance":"/api/crypto/verify","timestamp":1745120800}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found: key not found or unsuitable for verification.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key not found":{"description":"Key not found","value":{"type":"/errors/not-found","title":"Resource not found","status":404,"detail":"Key 'unknownKid' does not exist or lacks verify capability.","instance":"/api/crypto/verify","timestamp":1745120801}}}}}},"409":{"description":"Conflict: key is in a disallowed state (e.g., revoked).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid key state":{"description":"Invalid key state","value":{"type":"/errors/conflict","title":"Conflict","status":409,"detail":"Key 'myVerifyKeyKid' is revoked and cannot verify signatures.","instance":"/api/crypto/verify","timestamp":1745120802}}}}}},"413":{"description":"Payload Too Large: JWS string exceeds 5 MB.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"JWS too large":{"description":"JWS too large","value":{"type":"/errors/payload-too-large","title":"Payload too large","status":413,"detail":"JWS exceeds the maximum allowed size (5 000 000 bytes).","instance":"/api/crypto/verify","timestamp":1745120803}}}}}},"422":{"description":"Unprocessable Entity: malformed Compact JWS (parse error).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Malformed JWS":{"description":"Malformed JWS","value":{"type":"/errors/unprocessable-entity","title":"Unprocessable Entity","status":422,"detail":"JWS token is not a valid Compact JWS.","instance":"/api/crypto/verify","timestamp":1745120804}}}}}},"500":{"description":"Internal Server Error: unexpected error during verification.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/crypto/stream/verify":{"post":{"tags":[" Secure Streaming"],"summary":"Verify a detached-JWS (streaming).","description":"Two multipart/form-data parts:\n• metadata – JSON (VerifyDetachedJwsStreamRequest)\n with a detached-JWS (General-JSON).\n• file – the binary payload originally signed.\nExtracts kid and alg from the header, verifies\nand returns a VerifySignatureResponse.\n","operationId":"verifySignatureStream","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/VerifyDetachedJwsStreamRequest"},"file":{"type":"string","format":"binary","description":"Binary payload originally signed."}},"required":["file","metadata"]},"examples":{"Verify Request":{"description":"Verify Request","value":"--boundary\nContent-Disposition: form-data; name=\"metadata\"; filename=\"meta.json\"\nContent-Type: application/json\n\n{\n \"detachedJws\":\n \"{\"protected\":\"…\",\"signature\":null}\"\n}\n--boundary\nContent-Disposition: form-data; name=\"file\"; filename=\"payload.bin\"\nContent-Type: application/octet-stream\n\n\n--boundary--\n"}}}},"required":true},"responses":{"200":{"description":"Signature verified; JSON result returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifySignatureResponse"}}}},"400":{"description":"Malformed JWS or invalid Base64.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Unauthorized.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"kid not found or unsuitable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Unexpected failure.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/crypto/stream/sign":{"post":{"tags":[" Secure Streaming"],"summary":"Sign data (streaming).","description":"Consumes two multipart/form-data fields:
\n1. metadata â€“ JSON body SignStreamRequest
\n2. file â€“ binary data to sign

\nProduces a detached-JWS signature streamed back as\napplication/octet-stream.\n","operationId":"signDataStream","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/SignStreamRequest"},"file":{"type":"string","format":"binary","description":"Binary data to be signed."}},"required":["file","metadata"]},"examples":{"Sign Request":{"description":"Sign Request","value":"--boundary\nContent-Disposition: form-data; name=\"metadata\"; filename=\"meta.json\"\nContent-Type: application/json\n\n{ \"kid\":\"myPrivateKid\" }\n--boundary\nContent-Disposition: form-data; name=\"file\"; filename=\"image.png\"\nContent-Type: image/png\n\n…binary…\n--boundary--\n"}}}},"required":true},"responses":{"200":{"description":"Data signed successfully (stream).","headers":{"Crypto-Policy-Info":{"description":"Base64URL-encoded JSON payload (snake_case) describing key\nselection and policy warnings for the current request.\nDecode and deserialise into\n{@link co.ankatech.ankasecure.api.model.CryptoPolicyInfo}.\n","style":"simple","schema":{"$ref":"#/components/schemas/CryptoPolicyInfo"}}},"content":{"application/octet-stream":{}}},"400":{"description":"Malformed multipart or invalid data.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Unauthorized.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"kid not found or unsuitable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Unexpected failure during streaming signing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/crypto/stream/resign":{"post":{"tags":[" Secure Streaming"],"summary":"Re-sign data (streaming).","description":"Verifies a detached-JWS (oldJws) under oldKid—\neither the header’s kid or sourceKidOverride\nif the header lacks a kid—and immediately signs the same payload with\nnewKid. Streams only the new detached-JWS JSON back.\n","operationId":"resignDataStream","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/ResignDetachedJwsStreamRequest"},"file":{"type":"string","format":"binary","description":"Binary data to be re-signed."}},"required":["file","metadata"]},"examples":{"Re-sign Request":{"description":"Re-sign Request","value":"--boundary\nContent-Disposition: form-data; name=\"metadata\"; filename=\"meta.json\"\nContent-Type: application/json\n\n{\n \"oldJws\": \"{\"protected\":\"eyJhbGciOiJNSy1EU0EtNzc4Iiwia2lkIjoiLEGACYCLUxIn0\",\"signature\":null}\",\n \"newKid\": \"myNewSignKid\",\n \"sourceKidOverride\": \"legacySymKey\"\n}\n--boundary\nContent-Disposition: form-data; name=\"file\"; filename=\"document.pdf\"\nContent-Type: application/pdf\n\n%PDF-…\n--boundary--\n"}}}},"required":true},"responses":{"200":{"description":"File successfully re-signed; new signature streamed.","headers":{"Crypto-Policy-Info":{"description":"Base64URL-encoded JSON payload (snake_case) describing key\nselection and policy warnings for the current request.\nDecode and deserialise into\n{@link co.ankatech.ankasecure.api.model.CryptoPolicyInfo}.\n","style":"simple","schema":{"$ref":"#/components/schemas/CryptoPolicyInfo"}}},"content":{"application/octet-stream":{}}},"400":{"description":"Invalid Base64 or signature mismatch.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Unauthorized.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"oldKid/newKid not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Unexpected failure.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/crypto/stream/reencrypt":{"post":{"tags":[" Secure Streaming"],"summary":"Re-encrypt data (streaming).","description":"Decrypts the incoming ciphertext using oldKid (from the JWE header)\nand re-encrypts it on the fly with newKid (provided via query parameter).\nReturns a new multipart/mixed response containing the JWE header and the re-encrypted ciphertext.\n\"All key-selection metadata is returned in the single `Crypto-Policy-Info` response header.\n","operationId":"reencryptDataStream","parameters":[{"name":"newKid","in":"query","description":"Public-key **kid** for the new ciphertext.","required":true,"schema":{"type":"string"},"example":"mlkem-key-2025"},{"name":"sourceKidOverride","in":"query","description":"**Optional** fallback kid to decrypt a JWE header that\ncontains **no kid** (legacy / unmanaged artefacts).\n\n• Must reference a key already imported and flagged\n *decryptOnly*.\n\n• **Do not** send this parameter when the JWE header\n already includes a kid – the request will be\n rejected with HTTP 400.\n","required":false,"schema":{"type":"string"},"example":"rsa-legacy-2020"}],"requestBody":{"content":{"multipart/mixed":{"schema":{"type":"object","properties":{"header":{"$ref":"#/components/schemas/JwetGeneralJsonHeaderReencrypt"},"file":{"type":"string","format":"binary","description":"Original ciphertext envelope (binary)."}},"required":["file","header"]},"examples":{"Re-encrypt Request":{"description":"Re-encrypt Request","value":"--boundary\nContent-Type: application/jose+json\n\n{ \"protected\":\"…\",\"iv\":\"…\",\"tag\":null,\"ciphertext\":null,\n \"recipients\":[{\"header\":{\"alg\":\"ML-KEM-768\",\"kid\":\"oldKid\"},\n \"encrypted_key\":\"…\"}] }\n--boundary\nContent-Type: application/octet-stream\n\n\n--boundary--\n"}}},"multipart/form-data":{"schema":{"type":"object","properties":{"header":{"$ref":"#/components/schemas/JwetGeneralJsonHeaderReencrypt"},"file":{"type":"string","format":"binary","description":"Original ciphertext envelope (binary)."}},"required":["file","header"]}}},"required":true},"responses":{"200":{"description":"Ciphertext successfully re-encrypted.","headers":{"Crypto-Policy-Info":{"description":"Base64URL-encoded JSON payload (snake_case) describing key\nselection and policy warnings for the current request.\nDecode and deserialise into\n{@link co.ankatech.ankasecure.api.model.CryptoPolicyInfo}.\n","style":"simple","schema":{"$ref":"#/components/schemas/CryptoPolicyInfo"}}},"content":{"multipart/mixed":{"examples":{"Re-encrypt Response (truncated)":{"description":"Re-encrypt Response (truncated)","value":"------ankatech-abc123\nContent-Type: application/jose+json\n\n{\"protected\":\"…\",\"iv\":\"…\",\"tag\":null,\"ciphertext\":null,\n \"recipients\":[{\"header\":{\"alg\":\"ML-KEM-768\",\"kid\":\"newKid\"},\n \"encrypted_key\":\"…\"}]}\n------ankatech-abc123\nContent-Type: application/octet-stream\n\n\n------ankatech-abc123--\n"}}}}},"400":{"description":"Malformed multipart or invalid JWE.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Unauthorized.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"KID not found or unsuitable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Unexpected failure.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/crypto/stream/encrypt":{"post":{"tags":[" Secure Streaming"],"summary":"Encrypt data (streaming).","description":"Consumes two multipart/form-data fields:
\n1. metadata – JSON body EncryptStreamRequest
\n2. file – binary plaintext

\nProduces a multipart/mixed response where:
\n• Part 1 (application/jose+json) is a JWE General-JSON header with\n detached ciphertext.
\n• Part 2 (application/octet-stream) is the proprietary envelope\n [wkLen]‖wrappedKey‖[ivLen]‖iv‖ciphertext‖tag streamed on-the-fly.\n","operationId":"encryptStream","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/EncryptStreamRequest"},"file":{"type":"string","format":"binary","description":"Plaintext file (binary)."}},"required":["file","metadata"]},"examples":{"Encrypt-Stream-Request":{"summary":"Multipart request with metadata + file","description":"Encrypt-Stream-Request","value":"--boundary\nContent-Disposition: form-data; name=\"metadata\"; filename=\"metadata.json\"\nContent-Type: application/json\n\n{ \"kid\":\"myPublicKid\" }\n--boundary\nContent-Disposition: form-data; name=\"file\"; filename=\"secret.bin\"\nContent-Type: application/octet-stream\n\n\n--boundary--\n"}}}},"required":true},"responses":{"200":{"description":"Plaintext encrypted successfully.","headers":{"Crypto-Policy-Info":{"description":"Base64URL-encoded JSON payload (snake_case) describing key\nselection and policy warnings for the current request.\nDecode and deserialise into\n{@link co.ankatech.ankasecure.api.model.CryptoPolicyInfo}.\n","style":"simple","schema":{"$ref":"#/components/schemas/CryptoPolicyInfo"}}},"content":{"multipart/mixed":{"examples":{"JWET-Multipart-Response (truncated)":{"description":"JWET-Multipart-Response (truncated)","value":"------ankatech-b6e0f4c3\nContent-Type: application/jose+json\n\n{\"protected\":\"…\",\"iv\":\"…\",\"tag\":null,\"ciphertext\":null,\n \"recipients\":[{\"header\":{\"alg\":\"ML-KEM-768\",\"kid\":\"myPublicKid\"},\n \"encrypted_key\":\"…\"}]}\n------ankatech-b6e0f4c3\nContent-Type: application/octet-stream\n\n\n------ankatech-b6e0f4c3--\n"}}}}},"400":{"description":"Malformed multipart or invalid JSON/Base64.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Unauthorized.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"kid not found or unsuitable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Unexpected failure during streaming encryption.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/crypto/stream/decrypt":{"post":{"tags":[" Secure Streaming"],"summary":"Decrypt data (streaming).","description":"The request is multipart/mixed with two parts:\n

application/jose+json — JWE General-JSON header\n (detached ciphertext).
application/octet-stream — proprietary binary\n envelope followed by the ciphertext and GCM tag.

\nThe plaintext is streamed directly to the response body.\n","operationId":"decryptStream","requestBody":{"content":{"multipart/mixed":{"schema":{"type":"object","properties":{"header":{"$ref":"#/components/schemas/JwetGeneralJsonHeaderDecrypt"},"file":{"type":"string","format":"binary","description":"Binary envelope + ciphertext + tag."}},"required":["file","header"]},"examples":{"JWET-Decrypt-Request":{"summary":"Sample multipart request","description":"JWET-Decrypt-Request","value":"--boundary\nContent-Type: application/jose+json\n\n{ \"protected\":\"…\",\"iv\":\"…\",\"tag\":null,\"ciphertext\":null,\n \"recipients\":[{ \"header\":{\"alg\":\"ML-KEM-768\",\"kid\":\"myKeyId\"},\n \"encrypted_key\":\"…\"}] }\n--boundary\nContent-Type: application/octet-stream\n\n\n--boundary--\n"}}},"multipart/form-data":{"schema":{"type":"object","properties":{"header":{"$ref":"#/components/schemas/JwetGeneralJsonHeaderDecrypt"},"file":{"type":"string","format":"binary","description":"Binary envelope + ciphertext + tag."}},"required":["file","header"]}}},"required":true},"responses":{"200":{"description":"Ciphertext decrypted successfully (stream).","headers":{"Crypto-Policy-Info":{"description":"Base64URL-encoded JSON payload (snake_case) describing key\nselection and policy warnings for the current request.\nDecode and deserialise into\n{@link co.ankatech.ankasecure.api.model.CryptoPolicyInfo}.\n","style":"simple","schema":{"$ref":"#/components/schemas/CryptoPolicyInfo"}}},"content":{"application/octet-stream":{}}},"400":{"description":"Malformed multipart or invalid JWE header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Malformed-Header":{"description":"Malformed-Header","value":{"type":"https://docs.ankasecure.com/errors/invalid-header","title":"Invalid JWE header","status":400,"detail":"The JWE header is syntactically incorrect."}}}}}},"401":{"description":"Unauthorized.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"kid not found or unsuitable.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Unexpected error during streaming decryption.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/crypto/sign":{"post":{"tags":[" Secure"],"summary":"Sign data (JWS).","description":"Returns an RFC 7515 compact JWS generated with the\nprivate key associated with kid.\nSupported algorithms: ML-DSA, Falcon, RSA-PSS (PS256),\nECDSA (ES256/384/512).\n","operationId":"sign","requestBody":{"description":"JSON payload with the key identifier (kid) and the\nmessage (data) to sign, both Base64‑encoded.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignRequest"},"examples":{"Sign request":{"description":"Sign request","value":{"kid":"mySigningKeyKid","data":"SGVsbG8gQW5rYQ=="}}}}},"required":true},"responses":{"200":{"description":"JWS generated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignJwsResponse"},"examples":{"SignJwsResponse":{"description":"SignJwsResponse","value":{"jwsToken":"eyJraWQiOiJteVNpZ25pbmdLZXlLaWQiLCJhbGciOiJQUzI1NiJ9.SGVsbG8gQW5rYQ.L3NvbWVfY29tcGFjdF9zaWduYXR1cmU","keyRequested":"mySigningKeyKid","actualKeyUsed":"mySigningKeyKid_v2","algorithmUsed":"PS256","warnings":[]}}}}}},"400":{"description":"Bad Request: malformed Base64 or missing 'data' field.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid input":{"description":"Invalid input","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"'data' is not valid Base64 or missing.","instance":"/api/crypto/sign","timestamp":1745120700}}}}}},"413":{"description":"Payload Too Large: decoded data exceeds 5 MB.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Payload too large":{"description":"Payload too large","value":{"type":"/errors/payload-too-large","title":"Payload too large","status":413,"detail":"Decoded data exceeds the maximum allowed size (5 000 000 bytes).","instance":"/api/crypto/sign","timestamp":1745120701}}}}}},"404":{"description":"Not Found: key does not exist or lacks a private component.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key not found":{"description":"Key not found","value":{"type":"/errors/not-found","title":"Resource not found","status":404,"detail":"Key 'mySigningKeyKid' does not exist or lacks a private key.","instance":"/api/crypto/sign","timestamp":1745120702}}}}}},"409":{"description":"Conflict: key is in an invalid state (e.g., revoked or suspended).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid key state":{"description":"Invalid key state","value":{"type":"/errors/conflict","title":"Conflict","status":409,"detail":"Key 'mySigningKeyKid' is revoked and cannot be used for signing.","instance":"/api/crypto/sign","timestamp":1745120703}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error: unexpected error during signing.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/crypto/sign-encrypt":{"post":{"tags":[" Secure"],"summary":"Sign then encrypt data (nested JWE(JWS))","description":"Performs sign-then-encrypt operation: signs data with signKid, then encrypts\nthe resulting JWS with encryptKid to produce a nested JWE(JWS) structure.\n\nBoth keys must be either both symmetric or both asymmetric (no mixing).\nBoth keys must be different.\n\nThe outer JWE header will include cty=\"JWS\" to indicate nested content.\n","operationId":"signThenEncrypt","requestBody":{"description":"Data to sign and encrypt with two different keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignEncryptRequest"},"examples":{"Sign-encrypt request":{"description":"Sign-encrypt request","value":{"data":"SGVsbG8gQW5rYQ==","signKid":"mySignKey","encryptKid":"myEncryptKey","validityDays":365}}}}},"required":true},"responses":{"200":{"description":"Sign-then-encrypt operation successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignEncryptResponse"},"examples":{"SignEncryptResponse":{"description":"SignEncryptResponse","value":{"jweToken":"eyJraWQiOiJlbmNLZXkiLCJhbGciOiJNTC1LRU0tMTAyNCIsImVuYyI6IkEyNTZHQ00iLCJjdHkiOiJKV1MifQ...","signKeyRequested":"mySignKey","actualSignKeyUsed":"mySignKey","signAlgorithmUsed":"ML-DSA-87","signWarnings":[],"encryptionKeyRequested":"myEncKey","actualEncryptionKeyUsed":"myEncKey","encryptionAlgorithmUsed":"ML-KEM-1024+A256GCM","encryptionWarnings":[]}}}}}},"400":{"description":"Bad Request: invalid Base64, same kids, or key type mismatch","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid Base64":{"description":"Invalid Base64","value":{"type":"/errors/invalid-input","title":"Invalid Input","status":400,"detail":"Data is not valid Base64.","instance":"/api/crypto/sign-encrypt","timestamp":1734800000}},"Same kids (must be different)":{"description":"Same kids (must be different)","value":{"type":"/errors/invalid-input","title":"Invalid Input","status":400,"detail":"The signKid and encryptKid must be different keys.","instance":"/api/crypto/sign-encrypt","timestamp":1734800000}},"Key type mismatch (symmetric vs asymmetric)":{"description":"Key type mismatch (symmetric vs asymmetric)","value":{"type":"/errors/invalid-input","title":"Invalid Input","status":400,"detail":"The signKid and encryptKid must both be symmetric or both be asymmetric. Mixing key types is not permitted.","instance":"/api/crypto/sign-encrypt","timestamp":1734800000}}}}}},"404":{"description":"Not Found: key does not exist","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key not found":{"description":"Key not found","value":{"type":"/errors/not-found","title":"Resource Not Found","status":404,"detail":"Key not found with kid: myNonExistentKey","instance":"/api/crypto/sign-encrypt","timestamp":1734800000}}}}}},"409":{"description":"Conflict: invalid key state","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key revoked":{"description":"Key revoked","value":{"type":"/errors/invalid-key-state","title":"Invalid Key State","status":409,"detail":"The key with the specified kid is already revoked and cannot be used.","instance":"/api/crypto/sign-encrypt","timestamp":1734800000}}}}}},"413":{"description":"Payload Too Large: exceeds 5MB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Data exceeds limit":{"description":"Data exceeds limit","value":{"type":"/errors/payload-too-large","title":"Payload Too Large","status":413,"detail":"Data size exceeds the maximum allowed limit of 5MB.","instance":"/api/crypto/sign-encrypt","timestamp":1734800000}}}}}},"500":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Unexpected error":{"description":"Unexpected error","value":{"type":"/errors/internal","title":"Internal Server Error","status":500,"detail":"Failed to perform sign-then-encrypt operation.","instance":"/api/crypto/sign-encrypt","timestamp":1734800000}}}}}}}}},"/api/crypto/resign":{"post":{"tags":[" Secure"],"summary":"Re-sign a Compact JWS with a new key","description":"Verifies the incoming Compact JWS under its embedded `oldKid` (or an explicit override)\nand, if valid, produces a replacement signature with `newKid`. Useful for\nalgorithm migrations without touching payload bytes.\n","operationId":"resign","requestBody":{"description":"JSON object with:\n• `jwsToken` – Compact JWS to verify\n• `newKid` – kid to use for the new signature\n• `sourceKidOverride` – optional fallback kid if the header has no `kid`\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResignJwsRequest"},"examples":{"Standard flow (header has kid)":{"description":"Standard flow (header has kid)","value":{"jwsToken":"eyJraWQiOiJvbGRTaWduS2lkIiwiYWxnIjoiUC0yNTYifQ.SGVsbG8gQW5rYQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c","newKid":"myPostQuantumSignKid"}},"Override flow (header lacks kid)":{"description":"Override flow (header lacks kid)","value":{"jwsToken":"eyJhbGciOiJQMjU2In0.SGVsbG8gQW5rYQ.XYZ123...","newKid":"myPostQuantumSignKid","sourceKidOverride":"legacySignKeyV1"}}}}},"required":true},"responses":{"200":{"description":"Payload successfully re-signed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResignJwsResponse"},"examples":{"Re-sign response":{"description":"Re-sign response","value":{"jwsToken":"eyJraWQiOiJuZXdTaWduS2lkIiwiYWxnIjoiRkFMMTI4In0.SGVsbG8gQW5rYQ.XYZ123...","oldKeyRequested":"oldSignKid","oldKeyUsed":"oldSignKid_v2","oldKeyAlgorithmUsed":"PS256","newKeyRequested":"myPostQuantumSignKid","newKeyUsed":"myPostQuantumSignKid","newKeyAlgorithmUsed":"Falcon-512","warnings":["Key 'oldSignKid' nearing expiry"]}}}}}},"400":{"description":"Bad Request: either the JWS header has no `kid` and no override was provided,\nor both a header `kid` and `sourceKidOverride` were supplied.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Missing kid":{"description":"Missing kid","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"Missing 'kid' in JWS header and no 'sourceKidOverride' provided.","instance":"/api/crypto/resign","timestamp":1745120900}},"Conflicting parameters":{"description":"Conflicting parameters","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"Cannot specify both header 'kid' and 'sourceKidOverride'.","instance":"/api/crypto/resign","timestamp":1745120901}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found: oldKid or newKid does not exist or lacks the required capability.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key not found":{"description":"Key not found","value":{"type":"/errors/not-found","title":"Resource not found","status":404,"detail":"Key 'newKid' does not exist or cannot sign.","instance":"/api/crypto/resign","timestamp":1745120901}}}}}},"409":{"description":"Conflict: oldKid or newKid is in a disallowed state (revoked, suspended).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid key state":{"description":"Invalid key state","value":{"type":"/errors/conflict","title":"Conflict","status":409,"detail":"Key 'oldSignKid' is revoked and cannot verify.","instance":"/api/crypto/resign","timestamp":1745120902}}}}}},"413":{"description":"Payload Too Large: JWS exceeds the maximum allowed size (5 MB).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Payload too large":{"description":"Payload too large","value":{"type":"/errors/payload-too-large","title":"Payload too large","status":413,"detail":"JWS payload exceeds 5 000 000 bytes.","instance":"/api/crypto/resign","timestamp":1745120903}}}}}},"422":{"description":"Unprocessable Entity: incoming JWS is not valid Compact JWS.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid JWS":{"description":"Invalid JWS","value":{"type":"/errors/unprocessable-entity","title":"Unprocessable Entity","status":422,"detail":"Provided JWS token is not valid Compact JWS.","instance":"/api/crypto/resign","timestamp":1745120904}}}}}},"500":{"description":"Internal Server Error: unexpected error during re-sign.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/crypto/reencrypt":{"post":{"tags":[" Secure"],"summary":"Re-encrypt a Compact JWE","description":"Decrypts the incoming Compact JWE under its embedded kid,\nor under sourceKidOverride if no kid is present,\nthen re-encrypts into a fresh Compact JWE under newKid.\n","operationId":"reencrypt","requestBody":{"description":"JSON object with:\n• jweToken – original Compact JWE string to decrypt and re-encrypt\n• newKid – key ID for the new JWE’s public key\n• sourceKidOverride – **optional** key ID to use if the incoming JWE header has no kid\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReencryptJweRequest"},"examples":{"Without sourceKidOverride":{"description":"Without sourceKidOverride","value":{"jweToken":"eyJraWQiOiJvbGRLaWQiLCJhbGciOiJBZXIxMjgtQ0JDIiwiY3R5IjoiYXBwbGljYXRpb24vam9zZS1zdHJlYW0ifQ..IV.Ciphertext.Tag","newKid":"newPqcKemKey"}},"With sourceKidOverride":{"description":"With sourceKidOverride","value":{"jweToken":"eyJhbGciOiJBMjU2R0NNIn0..IV.Ciphertext.Tag","newKid":"newPqcKemKey","sourceKidOverride":"legacyRsaKey"}}}}},"required":true},"responses":{"200":{"description":"Re-encryption succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReencryptJweResponse"},"examples":{"ReencryptJweResponse":{"description":"ReencryptJweResponse","value":{"jweToken":"eyJraWQiOiJuZXdLaWQifQ..NewIV.NewCiphertext.NewTag","oldKeyRequested":"oldKey_v1","oldKeyUsed":"oldKey_v2","oldKeyAlgorithmUsed":"RSA-OAEP","newKeyRequested":"myNewMlkemKid","newKeyUsed":"myNewMlkemKid","newKeyAlgorithmUsed":"ML-KEM-768","warnings":["Old key nearing sunset date","New key usage at 90% capacity"],"errorMessage":null}}}}}},"400":{"description":"Bad Request: the JWE header is either missing its `kid` or both a `kid` and `sourceKidOverride`\nhave been supplied simultaneously, which is not allowed.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Missing kid in JWE header":{"description":"Missing kid in JWE header","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"Key ID not specified in JWE header.","instance":"/api/crypto/reencrypt","timestamp":1745120500}},"Conflict: both kid and sourceKidOverride provided":{"description":"Conflict: both kid and sourceKidOverride provided","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"Cannot specify both a 'kid' in the JWE header and a 'sourceKidOverride'. Please provide only one.","instance":"/api/crypto/reencrypt","timestamp":1745120501}}}}}},"404":{"description":"Not Found: source or destination key missing or unsuitable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key not found":{"description":"Key not found","value":{"type":"/errors/not-found","title":"Resource not found","status":404,"detail":"Key 'oldKey' does not exist or lacks a private key.","instance":"/api/crypto/reencrypt","timestamp":1745120501}}}}}},"409":{"description":"Conflict: key state invalid (e.g. revoked, suspended)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid key state":{"description":"Invalid key state","value":{"type":"/errors/conflict","title":"Conflict","status":409,"detail":"Key 'myNewMlkemKid' is suspended and cannot encrypt.","instance":"/api/crypto/reencrypt","timestamp":1745120502}}}}}},"413":{"description":"Payload Too Large: ciphertext or decrypted payload exceeds 5 MB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Payload too large":{"description":"Payload too large","value":{"type":"/errors/payload-too-large","title":"Payload too large","status":413,"detail":"Encrypted data exceeds the maximum allowed size (5 000 000 bytes).","instance":"/api/crypto/reencrypt","timestamp":1745120503}}}}}},"422":{"description":"Unprocessable Entity: malformed Compact JWE","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid JWE":{"description":"Invalid JWE","value":{"type":"/errors/unprocessable-entity","title":"Unprocessable Entity","status":422,"detail":"Provided JWE token is not valid Compact JWE.","instance":"/api/crypto/reencrypt","timestamp":1745120504}}}}}},"500":{"description":"Internal Server Error: unexpected crypto failure","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/crypto/encrypt":{"post":{"tags":[" Secure"],"summary":"Encrypt data (JWE).","description":"Encrypts Base64‑encoded data using the public key associated\nwith kid.\nSupported algorithms: ML‑KEM (KEM), RSA, ECC (ECIES).\n","operationId":"encrypt_1","requestBody":{"description":"JSON payload containing the key identifier (kid) and\nthe plaintext (data) to encrypt, both Base64‑encoded.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EncryptRequest"},"examples":{"Encrypt request":{"description":"Encrypt request","value":{"kid":"myKeyKid","data":"SGVsbG8gQW5rYQ=="}}}}},"required":true},"responses":{"200":{"description":"Encryption successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EncryptJweResponse"},"examples":{"EncryptJweResponse":{"description":"EncryptJweResponse","value":{"jweToken":"eyJraWQiOiJteV9LRUlfS2V5IiwgImFsZyI6Ik1MLUtFTS0xMDI0K0EyNTZHQ00ifQ..iv.CypherText.tag","keyRequested":"myKeyKid","actualKeyUsed":"myKeyKid_v2","algorithmUsed":"ML-KEM-1024+A256GCM","warnings":["Usage at 90% limit, rotation recommended soon.","Key 'myKeyKid' is nearing sunset; consider rotating soon"]}}}}}},"400":{"description":"Bad Request: input is not valid Base64","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid Base64":{"description":"Invalid Base64","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"'data' is not valid Base64.","instance":"/api/crypto/encrypt","timestamp":1745120400}}}}}},"413":{"description":"Payload Too Large: plaintext exceeds 5 MB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Payload too large":{"description":"Payload too large","value":{"type":"/errors/payload-too-large","title":"Payload too large","status":413,"detail":"'data' exceeds the maximum allowed size (5 000 000 bytes).","instance":"/api/crypto/encrypt","timestamp":1745120401}}}}}},"404":{"description":"Not Found: specified key does not exist or lacks a public component","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Unknown key":{"description":"Unknown key","value":{"type":"/errors/not-found","title":"Resource not found","status":404,"detail":"Key 'myKeyKid' does not exist or has no public key.","instance":"/api/crypto/encrypt","timestamp":1745120402}}}}}},"409":{"description":"Conflict: key is in an invalid state (e.g. suspended or revoked)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid key state":{"description":"Invalid key state","value":{"type":"/errors/conflict","title":"Conflict","status":409,"detail":"Key 'myKeyKid_v2' is suspended and cannot encrypt.","instance":"/api/crypto/encrypt","timestamp":1745120403}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error: unexpected error during encryption","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/crypto/decrypt":{"post":{"tags":[" Secure"],"summary":"Decrypt a Compact JWE","description":"Parses and decrypts the given Compact JWE string using the private key\nidentified by its kid header. Returns the plaintext\n(Base64-encoded) plus metadata about key selection, algorithm, and\nany warnings.\n","operationId":"decrypt","requestBody":{"description":"JSON object with exactly one field:\n• jweToken – the Compact JWE (RFC 7516) to decrypt\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecryptJweRequest"},"examples":{"DecryptJweRequest":{"description":"DecryptJweRequest","value":{"jweToken":"eyJraWQiOiJteUtleUtpZCIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJSQXEtT0FFUC0yNTYiLCJjdHkiOiJhcHBsaWNhdGlvbi9vY3RldC1zdHJlYW0ifQ..vUWhGqCHG2jc-tMc.Kut2XDEyqMvu8Q.YWmUX9yrPq5R6w"}}}}},"required":true},"responses":{"200":{"description":"Data decrypted successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecryptResponse"},"examples":{"DecryptResponse":{"description":"DecryptResponse","value":{"decryptedData":"SGVsbG8gQW5rYQ==","keyRequested":"myKeyKid","actualKeyUsed":"myKeyKid","algorithmUsed":"ML-KEM-768","warnings":[]}}}}}},"400":{"description":"Bad Request: malformed Base64 or missing/blank JWE header 'kid'.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid input":{"description":"Invalid input","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"'jweToken' is not valid Base64 or 'kid' header is missing.","instance":"/api/crypto/decrypt","timestamp":1745120300}}}}}},"413":{"description":"Payload Too Large: plaintext exceeds 5 MB after decryption.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Payload too large":{"description":"Payload too large","value":{"type":"/errors/payload-too-large","title":"Payload too large","status":413,"detail":"Decrypted plaintext exceeds the maximum allowed size (5 000 000 bytes).","instance":"/api/crypto/decrypt","timestamp":1745120301}}}}}},"404":{"description":"Not Found: specified key does not exist or lacks a private component.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key not found":{"description":"Key not found","value":{"type":"/errors/not-found","title":"Resource not found","status":404,"detail":"Key 'myKeyKid' does not exist or has no private key.","instance":"/api/crypto/decrypt","timestamp":1745120302}}}}}},"409":{"description":"Conflict: key is in an invalid state (e.g. revoked or suspended).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid key state":{"description":"Invalid key state","value":{"type":"/errors/conflict","title":"Conflict","status":409,"detail":"Key 'myKeyKid' is suspended and cannot decrypt.","instance":"/api/crypto/decrypt","timestamp":1745120303}}}}}},"422":{"description":"Unprocessable Entity: JWE Compact serialization is malformed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Malformed JWE":{"description":"Malformed JWE","value":{"type":"/errors/invalid-input","title":"Unprocessable Entity","status":422,"detail":"'jweToken' is not a valid Compact JWE.","instance":"/api/crypto/decrypt","timestamp":1745120304}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error: unexpected error during decryption.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/crypto/decrypt-verify":{"post":{"tags":[" Secure"],"summary":"Decrypt then verify data (nested JWE(JWS) → plaintext)","description":"Performs decrypt-then-verify operation: decrypts nested JWE with decryptKid,\nthen verifies the inner JWS signature with verifyKid to extract original plaintext.\n\nBoth keys must be either both symmetric or both asymmetric (no mixing).\nBoth keys must be different.\n\nIf signature verification fails, returns 422 Unprocessable Entity.\n","operationId":"decryptThenVerify","requestBody":{"description":"Nested JWE(JWS) token to decrypt and verify","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecryptVerifyRequest"},"examples":{"Decrypt-verify request":{"description":"Decrypt-verify request","value":{"jweToken":"eyJraWQiOiJlbmNLZXkiLCJhbGciOiJNTC1LRU0tMTAyNCIsImVuYyI6IkEyNTZHQ00iLCJjdHkiOiJKV1MifQ...","decryptKid":"myDecryptKey","verifyKid":"myVerifyKey"}}}}},"required":true},"responses":{"200":{"description":"Decrypt-then-verify operation successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecryptVerifyResponse"},"examples":{"DecryptVerifyResponse":{"description":"DecryptVerifyResponse","value":{"data":"SGVsbG8gQW5rYQ==","decryptKeyRequested":"myDecryptKey","actualDecryptKeyUsed":"myDecryptKey","decryptAlgorithmUsed":"ML-KEM-1024+A256GCM","decryptWarnings":[],"verifyKeyRequested":"myVerifyKey","actualVerifyKeyUsed":"myVerifyKey","verifyAlgorithmUsed":"ML-DSA-87","verifyWarnings":[]}}}}}},"400":{"description":"Bad Request: malformed token, same kids, or key type mismatch","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"JWE token missing":{"description":"JWE token missing","value":{"type":"/errors/invalid-input","title":"Invalid Input","status":400,"detail":"JWE token is missing.","instance":"/api/crypto/decrypt-verify","timestamp":1734800100}},"Same kids (must be different)":{"description":"Same kids (must be different)","value":{"type":"/errors/invalid-input","title":"Invalid Input","status":400,"detail":"The decryptKid and verifyKid must be different keys.","instance":"/api/crypto/decrypt-verify","timestamp":1734800100}},"Key type mismatch (symmetric vs asymmetric)":{"description":"Key type mismatch (symmetric vs asymmetric)","value":{"type":"/errors/invalid-input","title":"Invalid Input","status":400,"detail":"The decryptKid and verifyKid must both be symmetric or both be asymmetric. Mixing key types is not permitted.","instance":"/api/crypto/decrypt-verify","timestamp":1734800100}}}}}},"404":{"description":"Not Found: key does not exist","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key not found":{"description":"Key not found","value":{"type":"/errors/not-found","title":"Resource Not Found","status":404,"detail":"Key not found with kid: myMissingKey","instance":"/api/crypto/decrypt-verify","timestamp":1734800100}}}}}},"409":{"description":"Conflict: invalid key state","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key revoked":{"description":"Key revoked","value":{"type":"/errors/invalid-key-state","title":"Invalid Key State","status":409,"detail":"The key with the specified kid is already revoked and cannot be used.","instance":"/api/crypto/decrypt-verify","timestamp":1734800100}}}}}},"413":{"description":"Payload Too Large: exceeds 5MB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Nested token too large":{"description":"Nested token too large","value":{"type":"/errors/payload-too-large","title":"Payload Too Large","status":413,"detail":"Encrypted data size exceeds the maximum allowed limit of 5MB.","instance":"/api/crypto/decrypt-verify","timestamp":1734800100}}}}}},"422":{"description":"Unprocessable Entity: invalid signature or malformed JWE/JWS","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid signature":{"description":"Invalid signature","value":{"type":"/errors/unprocessable-entity","title":"Unprocessable Entity","status":422,"detail":"Signature verification failed","instance":"/api/crypto/decrypt-verify","timestamp":1734800100}},"Malformed nested token":{"description":"Malformed nested token","value":{"type":"/errors/unprocessable-entity","title":"Unprocessable Entity","status":422,"detail":"The provided nested JWE(JWS) token is malformed or invalid.","instance":"/api/crypto/decrypt-verify","timestamp":1734800100}}}}}},"500":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Unexpected error":{"description":"Unexpected error","value":{"type":"/errors/internal","title":"Internal Server Error","status":500,"detail":"Failed to perform decrypt-then-verify operation.","instance":"/api/crypto/decrypt-verify","timestamp":1734800100}}}}}}}}},"/api/key-management/keys/{kid}":{"delete":{"tags":[" Key Management"],"summary":"Remove a key by kid.","description":"Deletes the specified key from the keystore. This operation is irreversible.","operationId":"removeKey","parameters":[{"name":"kid","in":"path","description":"Identifier of the key to remove.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Key removed successfully (no content)."},"400":{"description":"Invalid input: missing or malformed parameters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Missing kid":{"description":"Missing kid","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"'kid' must not be blank.","instance":"/api/key-management/keys/","timestamp":1745120200}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Forbidden: authenticated user lacks the required scope or operation not allowed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Key not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Unknown kid":{"description":"Unknown kid","value":{"type":"/errors/not-found","title":"Resource not found","status":404,"detail":"Key 'nonexistentKey' does not exist.","instance":"/api/key-management/keys/nonexistentKey","timestamp":1745120100}}}}}},"409":{"description":"Conflict: key is in an invalid state (e.g., already revoked).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key in invalid state":{"description":"Key in invalid state","value":{"type":"/errors/invalid-key-state","title":"Conflict","status":409,"detail":"Key 'myKey' is disabled and cannot be removed.","instance":"/api/key-management/keys/myKey","timestamp":1745120250}}}}}},"500":{"description":"Internal Server Error: unexpected error while removing the key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"patch":{"tags":[" Key Management"],"summary":"Partially update a key (JSON Merge-Patch)","description":"Applies an RFC 7396 Merge-Patch to the specified key. Only the fields\npresent in the payload are evaluated against the lifecycle and limit\nvalidation rules before persisting any change.\n","operationId":"patchKey","parameters":[{"name":"kid","in":"path","description":"Key identifier","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"RFC 7396 Merge-Patch document. Only include fields you wish to change.\n","content":{"application/merge-patch+json":{"schema":{"type":"object"},"examples":{"Extend expiresAt":{"description":"Extend expiresAt","value":{"expiresAt":"2025-12-31T23:59:59Z"}},"Increase maxUsageLimit":{"description":"Increase maxUsageLimit","value":{"maxUsageLimit":10000}},"Set soft limits":{"description":"Set soft limits","value":{"softUsageLimit":5000,"softLimitExpiration":"2025-10-01T00:00:00Z"}},"Combined patch":{"description":"Combined patch","value":{"softUsageLimit":5000,"maxUsageLimit":10000,"softLimitExpiration":"2025-10-01T00:00:00Z","expiresAt":"2025-12-31T23:59:59Z"}}}},"application/json":{"schema":{"$ref":"#/components/schemas/JsonNode"}}},"required":true},"responses":{"204":{"description":"Patch applied successfully (no content)."},"400":{"description":"Invalid input: malformed patch or illegal field values.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid field combination":{"description":"Invalid field combination","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"'softUsageLimit' must be lower than 'maxUsageLimit'.","instance":"/api/key-management/keys/myKey","timestamp":1745120800}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Forbidden: authenticated user lacks the required scope or operation not allowed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Key not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Unknown kid":{"description":"Unknown kid","value":{"type":"/errors/not-found","title":"Resource not found","status":404,"detail":"Key 'nonexistentKey' does not exist.","instance":"/api/key-management/keys/nonexistentKey","timestamp":1745120850}}}}}},"409":{"description":"Conflict: lifecycle or limit validation failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Lifecycle conflict":{"description":"Lifecycle conflict","value":{"type":"/errors/invalid-key-state","title":"Conflict","status":409,"detail":"Key 'myKey' is revoked and cannot be modified.","instance":"/api/key-management/keys/myKey","timestamp":1745120900}}}}}},"413":{"description":"Payload Too Large: patch document exceeds server limits.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Patch too large":{"description":"Patch too large","value":{"type":"/errors/payload-too-large","title":"Payload too large","status":413,"detail":"Patch document exceeds the maximum allowed size (1 MB).","instance":"/api/key-management/keys/myKey","timestamp":1745120950}}}}}},"500":{"description":"Internal Server Error: unexpected error while applying the patch.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/monitoring/policy-cache/stats":{"get":{"tags":["Policy Cache Monitoring"],"summary":"Get policy cache statistics","description":"Returns detailed statistics for Caffeine caches and decision cache","operationId":"getCacheStats","responses":{"200":{"description":"Statistics retrieved successfully","content":{"*/*":{"schema":{"type":"object","additionalProperties":{}}}}}}}},"/api/monitoring/policy-cache/health":{"get":{"tags":["Policy Cache Monitoring"],"summary":"Policy cache health check","description":"Checks if policy cache system is healthy and Redis Pub/Sub listener is active","operationId":"getHealth","responses":{"200":{"description":"System is healthy","content":{"*/*":{"schema":{"type":"object","additionalProperties":{}}}}},"503":{"description":"System is unhealthy","content":{"*/*":{"schema":{"type":"object","additionalProperties":{}}}}}}}},"/api/migration/keys/{kid}":{"get":{"tags":["Migration"],"summary":"Export a key by kid (public portion if asymmetric).","description":"Returns the key metadata.\n• If the key is asymmetric, publicKey is included.\n• If the key is symmetric (kty = oct), the secret\n material is deliberately omitted.\nThe response still conveys lifecycle data such as usage counts,\nexpiry and status (ACTIVE, REVOKED…).\n","operationId":"exportKey","parameters":[{"name":"kid","in":"path","description":"Identifier of the key to export","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key exported successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyExportResponse"},"examples":{"Asymmetric key (RSA‑2048)":{"description":"Asymmetric key (RSA‑2048)","value":{"modelVersion":"v1.0","kid":"myRsaKey","uuid":"550e8400-e29b-41d4-a716-446655440000","kty":"RSA","alg":"RSA-2048","publicKey":"BASE64-ENCODED-PUBLIC-KEY","keyOps":["encrypt","decrypt"],"exportable":true,"createdAt":"2025-01-15T10:20:00Z","expiresAt":null,"softLimitExpiration":null,"usageCount":15,"lastUsedAt":"2025-01-18T10:10:00Z","softUsageLimit":null,"maxUsageLimit":null,"status":"ACTIVE","nextKid":null,"previousKid":null,"hash":"F6A9B8D2..."}},"Symmetric key (AES‑256, secret omitted)":{"description":"Symmetric key (AES‑256, secret omitted)","value":{"modelVersion":"v1.0","kid":"mySymKey","kty":"oct","alg":"AES-256","keyOps":["encrypt","decrypt"],"exportable":false,"createdAt":"2025-03-02T15:00:00Z","expiresAt":"2030-03-02T15:00:00Z","usageCount":45,"status":"ACTIVE"}}}}}},"404":{"description":"Key not found.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Unknown kid":{"description":"Unknown kid","value":{"type":"/errors/not-found","title":"Resource not found","status":404,"detail":"Key 'nonexistent' does not exist.","instance":"/api/key-management/keys/nonexistent","timestamp":1745119400}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error: cryptographic or keystore failure.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/license/metrics":{"get":{"tags":["License Metrics"],"summary":"Get license validation metrics","description":"Returns real-time metrics about license validation behavior, including the percentage of requests validated strictly vs allowed without validation. Useful for monitoring service availability vs enforcement tradeoff.","operationId":"getMetrics","responses":{"200":{"description":"Metrics retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseValidationMetrics"}}}},"401":{"description":"Unauthorized - valid JWT required","content":{"*/*":{"schema":{"$ref":"#/components/schemas/LicenseValidationMetrics"}}}},"403":{"description":"Forbidden - requires ADMIN or MONITORING role","content":{"*/*":{"schema":{"$ref":"#/components/schemas/LicenseValidationMetrics"}}}}}}},"/api/key-management/supported-algorithms":{"get":{"tags":[" Key Management"],"summary":"Get supported algorithms (crypto-agility)","description":"Returns each supported kty + alg pair, its permitted\nJWK keyOps, lifecycle status, optional\nsunsetDate, and advisory note.","operationId":"getSupportedAlgorithms","responses":{"200":{"description":"Supported algorithms list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SupportedAlgorithm"}},"examples":{"SupportedAlgorithm list":{"description":"SupportedAlgorithm list","value":[{"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."}]}}}}},"400":{"description":"Invalid input: malformed request parameters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Bad query parameter":{"description":"Bad query parameter","value":{"type":"/errors/invalid-input","title":"Invalid input","status":400,"detail":"Parameter 'status' must be one of ACTIVE|LEGACY|RECOMMENDED.","instance":"/api/key-management/supported-algorithms","timestamp":1745120400}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Forbidden: authenticated user lacks the required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error: unexpected error while retrieving algorithms.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/key-management/keys/{kid}/metadata":{"get":{"tags":[" Key Management"],"summary":"Retrieve key metadata (no cryptographic material)","description":"Returns comprehensive metadata for a single key including:\n- Lifecycle information (status, created/expires timestamps)\n- Usage tracking (usage count, limits)\n- Algorithm details (kty, alg)\n- Capability flags (exportable, legacy, keyOps)\n- Integrity verification (hash/fingerprint)\n\nThis endpoint is suitable for administrative dashboards, key inventory\nsystems, and compliance audits where cryptographic material exposure\nis unnecessary.\n\n**Note**: To retrieve the public key material, use the migration endpoint\nGET /api/migration/keys/{kid} which enforces exportable flag validation.\n","operationId":"getKeyMetadata","parameters":[{"name":"kid","in":"path","description":"Key identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key metadata retrieved successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeySummaryResponse"},"examples":{"ML-KEM-1024 key (exportable)":{"description":"ML-KEM-1024 key (exportable)","value":{"kid":"myKemKey","kty":"ML-KEM","alg":"ML-KEM-1024","keyOps":["encrypt","decrypt"],"exportable":true,"legacy":false,"status":"ACTIVE","createdAt":"2025-01-15T10:20:00Z","expiresAt":"2030-01-15T10:20:00Z","softLimitExpiration":"2029-07-15T10:20:00Z","usageCount":1243,"softUsageLimit":900000,"maxUsageLimit":1000000,"hash":"F6A9B8D2E4C1A7F3B9D8E2A4C6F1B3D5E7A9C2F4B6D8E1A3C5F7B9D2E4A6C8F1","nextKid":null,"previousKid":null}},"RSA-2048 key (non-exportable)":{"description":"RSA-2048 key (non-exportable)","value":{"kid":"myRsaKey","kty":"RSA","alg":"RSA-2048","keyOps":["sign","verify"],"exportable":false,"legacy":false,"status":"ACTIVE","createdAt":"2024-06-01T08:15:30Z","expiresAt":"2029-06-01T08:15:30Z","softLimitExpiration":"2028-12-01T08:15:30Z","usageCount":45032,"softUsageLimit":80000,"maxUsageLimit":100000,"hash":"A3B5C7D9E1F2A4B6C8D0E2F4A6B8C0D2E4F6A8B0C2D4E6F8A0B2C4D6E8F0A2B4","nextKid":null,"previousKid":null}},"AES-256 symmetric key":{"description":"AES-256 symmetric key","value":{"kid":"myAesKey","kty":"oct","alg":"A256GCM","keyOps":["encrypt","decrypt"],"exportable":false,"legacy":false,"status":"ACTIVE","createdAt":"2025-01-10T12:00:00Z","expiresAt":null,"softLimitExpiration":null,"usageCount":892,"maxUsageLimit":0,"hash":"D1F3A5B7C9E2F4A6B8D0E2F4A6B8C0D2E4F6A8B0C2D4E6F8A0B2C4D6E8F0A2B4","nextKid":null,"previousKid":null}}}}}},"400":{"description":"Invalid input: malformed kid parameter.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Invalid kid format":{"description":"Invalid kid format","value":{"type":"/errors/invalid-input","title":"Invalid Input","status":400,"detail":"Key identifier (kid) must not be empty or contain only whitespace.","instance":"/api/key-management/keys/ /metadata","timestamp":1745120100}}}}}},"401":{"description":"Unauthorized: missing or invalid JWT token.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Bearer token missing":{"description":"Bearer token missing","value":{"type":"/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Authentication credentials were not provided.","instance":"/api/key-management/keys/myKey/metadata","timestamp":1745120200}}}}}},"403":{"description":"Forbidden: authenticated user lacks required scope.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Insufficient permissions":{"description":"Insufficient permissions","value":{"type":"/errors/forbidden","title":"Forbidden","status":403,"detail":"Insufficient permissions. Required scope: key_management.viewKeyMetadata","instance":"/api/key-management/keys/myKey/metadata","timestamp":1745120300}}}}}},"404":{"description":"Key not found with the specified identifier.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Key does not exist":{"description":"Key does not exist","value":{"type":"/errors/not-found","title":"Resource Not Found","status":404,"detail":"Key not found for kid=nonExistentKey","instance":"/api/key-management/keys/nonExistentKey/metadata","timestamp":1745120400}}}}}},"500":{"description":"Internal server error during key retrieval.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"},"examples":{"Keystore access failure":{"description":"Keystore access failure","value":{"type":"/errors/internal-error","title":"Internal Server Error","status":500,"detail":"Unexpected error occurred while retrieving key metadata from keystore.","instance":"/api/key-management/keys/myKey/metadata","timestamp":1745120500}}}}}}}}}},"components":{"schemas":{"AlgorithmPolicy":{"type":"object","description":"Algorithm transformation policy","properties":{"allowLegacyHash":{"type":"boolean","default":false,"description":"Allow legacy hash algorithms (SHA-1, MD5).\n- false (default): Reject PKCS#7 files using SHA-1/MD5 (security policy)\n- true: Allow legacy hashes (for compatibility with very old files)\n","example":false},"contentEncryptionUpgrade":{"type":"string","default":"AES_GCM","description":"Content encryption upgrade strategy.\n- AES_GCM (default): Upgrade AES-CBC → AES-GCM, 3DES → AES-128-GCM\n- PRESERVE: Keep original algorithm if supported (not recommended)\n","enum":["AES_GCM","PRESERVE"],"example":"AES_GCM"}}},"Pkcs7ConversionStreamRequest":{"type":"object","description":"Metadata for streaming PKCS#7 to JOSE conversion (produces detached JOSE format)","properties":{"decryptionKid":{"type":"string","description":"Kid for decrypting EnvelopedData or SignedAndEnvelopedData. Required when PKCS#7 contains encrypted content. Obtain from /analyze-pkcs7 response: recommendations.requiredKeys[].kid","example":"legacy-recipient-key"},"serialization":{"type":"string","default":"AUTO","description":"Serialization mode (streaming produces detached format, ignores this field)","enum":["AUTO","COMPACT","JSON"]},"targetFormat":{"type":"string","default":"AUTO","description":"Target format (streaming auto-detects from PKCS#7 type, ignores this field)","enum":["AUTO","JWS","JWE","JWE_JWS_NESTED"]},"validateCertificates":{"type":"boolean","default":false,"description":"Whether to validate PKCS#7 certificate chains (optional, expensive)"},"validateTimestamp":{"type":"boolean","default":false,"description":"Whether to validate RFC 3161 timestamps (not yet available)"},"algorithmPolicy":{"$ref":"#/components/schemas/AlgorithmPolicy","description":"Algorithm transformation policy (CBC→GCM upgrade, legacy hash handling)"}},"required":["serialization","targetFormat"]},"Pkcs7AnalysisStreamRequest":{"type":"object","description":"Optional metadata for streaming PKCS#7 analysis","properties":{"decryptionKid":{"type":"string","description":"Optional kid for decrypting encrypted PKCS#7"},"validateCertificates":{"type":"boolean","default":false,"description":"Perform certificate chain validation"},"validateTimestamp":{"type":"boolean","default":false,"description":"Validate RFC 3161 timestamps (not yet available)"}}},"ConversionRecommendations":{"type":"object","description":"Recommendations for migration to JOSE","properties":{"migrationPath":{"type":"string","description":"Recommended migration path","enum":["CONVERT_TO_JWS_COMPACT","CONVERT_TO_JWE_COMPACT","CONVERT_TO_JWE_JWS_COMPACT","CONVERT_TO_JWS_JSON","CONVERT_TO_JWE_JSON","CONVERT_TO_JWE_JWS_JSON"],"example":"CONVERT_TO_JWE_JWS_COMPACT"},"requiredKeys":{"type":"array","description":"Required keys for conversion (must be imported via /api/migration/private-keys)","items":{"$ref":"#/components/schemas/RequiredKey"}},"estimatedComplexity":{"type":"string","description":"Estimated complexity level","enum":["LOW","MEDIUM","HIGH"],"example":"MEDIUM"},"phaseAvailability":{"type":"string","description":"Availability status for this conversion","enum":["AVAILABLE","NOT_YET_AVAILABLE"],"example":"AVAILABLE"}}},"DetectedFormat":{"type":"object","description":"Detected PKCS#7/CMS format and structure type","properties":{"standard":{"type":"string","description":"Standard detected (PKCS#7 or CMS)","example":"CMS"},"structure":{"type":"string","description":"Structure type detected","enum":["SignedData","EnvelopedData","SignedAndEnvelopedData","Nested_EnvelopedData_SignedData"],"example":"SignedAndEnvelopedData"},"contentTypeOID":{"type":"string","description":"Content-type OID from PKCS#7 structure","example":"1.2.840.113549.1.7.1"},"encoding":{"type":"string","description":"Encoding format (always DER for PKCS#7)","example":"DER"},"payloadEmbedded":{"type":"boolean","description":"Whether payload is embedded (true) or detached (false)","example":true}}},"EncryptionMetadata":{"type":"object","description":"Encryption algorithm and parameters","properties":{"contentEncryptionAlgorithmOID":{"type":"string","description":"Content encryption algorithm OID","example":"2.16.840.1.101.3.4.1.42"},"contentEncryptionAlgorithm":{"type":"string","description":"Content encryption algorithm name","example":"AES-256-CBC"},"ivLength":{"type":"integer","format":"int32","description":"Initialization Vector length in bytes","example":16}}},"Pkcs7AnalysisResponse":{"type":"object","description":"Detailed analysis of PKCS#7/CMS file structure with conversion recommendations.","properties":{"detectedFormat":{"$ref":"#/components/schemas/DetectedFormat","description":"Detected PKCS#7/CMS format information"},"signers":{"type":"array","description":"List of signers found in the PKCS#7 structure","items":{"$ref":"#/components/schemas/SignerMetadata"}},"recipients":{"type":"array","description":"List of recipients found in the PKCS#7 structure","items":{"$ref":"#/components/schemas/RecipientMetadata"}},"encryption":{"$ref":"#/components/schemas/EncryptionMetadata","description":"Encryption metadata (present only for EnvelopedData)"},"supportStatus":{"$ref":"#/components/schemas/SupportStatus","description":"Conversion support status and reasons"},"recommendations":{"$ref":"#/components/schemas/ConversionRecommendations","description":"Recommendations for successful conversion to JOSE"}},"required":["detectedFormat","supportStatus"]},"ReasonCode":{"type":"object","description":"Reason code explaining support or limitation","properties":{"code":{"type":"string","description":"Machine-readable code","example":"MULTIPLE_SIGNERS_REQUIRES_JWS_JSON"},"severity":{"type":"string","description":"Severity level","enum":["INFO","WARNING","ERROR"],"example":"INFO"},"message":{"type":"string","description":"Human-readable message","example":"Detected 3 signers. Migration will require JWS JSON Serialization (not Compact)."}}},"RecipientMetadata":{"type":"object","description":"Metadata for a recipient in the PKCS#7 structure","properties":{"index":{"type":"integer","format":"int32","description":"Recipient index (0-based)","example":0},"issuerDN":{"type":"string","description":"Issuer Distinguished Name from recipient certificate","example":"CN=Example User, O=Example Corp, C=US"},"serialNumber":{"type":"string","description":"Certificate serial number (hexadecimal)","example":"0x9F8E7D6C5B4A3B2C"},"keyEncryptionAlgorithmOID":{"type":"string","description":"Key encryption algorithm OID","example":"1.2.840.113549.1.1.1"},"keyEncryptionAlgorithm":{"type":"string","description":"Key encryption algorithm name","example":"RSA"},"certificatePresent":{"type":"boolean","description":"Whether recipient certificate is present in PKCS#7 structure","example":true},"certificatePEM":{"type":"string","description":"Recipient certificate in PEM format (if present)"}}},"RequiredKey":{"type":"object","description":"Key required for PKCS#7 decryption or verification","properties":{"purpose":{"type":"string","description":"Purpose of this key","enum":["decryption","verification"],"example":"decryption"},"issuerDN":{"type":"string","description":"Issuer DN that must match the imported key","example":"CN=Example User, O=Example Corp, C=US"},"serialNumber":{"type":"string","description":"Serial number that must match the imported key","example":"0x9F8E7D6C5B4A3B2C"},"algorithm":{"type":"string","description":"Algorithm required for this key","example":"RSA"},"importHint":{"type":"string","description":"Hint for importing the key","example":"Use POST /api/migration/private-keys to import matching RSA key and certificate"}}},"SignerMetadata":{"type":"object","description":"Metadata for a signer in the PKCS#7 structure","properties":{"index":{"type":"integer","format":"int32","description":"Signer index (0-based)","example":0},"issuerDN":{"type":"string","description":"Issuer Distinguished Name from signer certificate","example":"CN=Example CA Authority, O=Example Organization, C=US"},"serialNumber":{"type":"string","description":"Certificate serial number (hexadecimal)","example":"0x4A3F2E1D5B6C7A8B"},"signatureAlgorithmOID":{"type":"string","description":"Signature algorithm OID","example":"1.2.840.113549.1.1.11"},"signatureAlgorithm":{"type":"string","description":"Signature algorithm name","example":"SHA256withRSA"},"digestAlgorithmOID":{"type":"string","description":"Digest algorithm OID","example":"2.16.840.1.101.3.4.2.1"},"digestAlgorithm":{"type":"string","description":"Digest algorithm name","example":"SHA-256"},"certificatePresent":{"type":"boolean","description":"Whether signer certificate is present in PKCS#7 structure","example":true},"certificatePEM":{"type":"string","description":"Signer certificate in PEM format (if present)"},"certificateChainLength":{"type":"integer","format":"int32","description":"Length of certificate chain","example":3},"keyUsage":{"type":"array","description":"KeyUsage bits from certificate","example":["digitalSignature","nonRepudiation"],"items":{"type":"string"}},"timestampPresent":{"type":"boolean","description":"Whether RFC 3161 timestamp is present","example":true},"timestampTSA":{"type":"string","description":"Timestamp Authority Distinguished Name (if timestamp present)","example":"CN=TSA Example Authority"},"timestampGenTime":{"type":"string","description":"Timestamp generation time in ISO-8601 format (if timestamp present)","example":"2025-12-21T15:30:00Z"}}},"SupportStatus":{"type":"object","description":"Support status for JOSE conversion","properties":{"supported":{"type":"boolean","description":"Whether conversion is supported with current implementation","example":true},"reasons":{"type":"array","description":"Detailed reason codes explaining support status","items":{"$ref":"#/components/schemas/ReasonCode"}}}},"ImportPkcs12Metadata":{"type":"object","description":"Describes the metadata needed to import a PKCS#12 (.p12/.pfx) file,\nincluding the kid, optional password, and Base64-encoded file content.\n","properties":{"kid":{"type":"string","description":"The kid under which the private key will be stored in the keystore.\nRequired; if it already exists, the system may override or fail\ndepending on the logic.\n","example":"myPrivateKeyKid","minLength":1},"p12Password":{"type":"string","description":"Password for opening the .p12/.pfx file, if it is password-protected.\nThis field may be empty or null if the PKCS#12 is not protected.\n","example":"myPkcs12Password"},"p12FileBase64":{"type":"string","description":"Base64-encoded PKCS#12 (.p12 or .pfx) file content. This should be the raw bytes of the\nPKCS#12 file, including the private key and any certificates, all encoded in Base64.\n","example":"MIIKvwIBAzCCChAGCSqGSIb3DQEHAaCCCgE...","minLength":1},"validationMode":{"type":"string","description":"Certificate validation mode (STRICT, IMPORT_ONLY, SKIP).\nIf not specified, uses system default from configuration.\n","enum":["STRICT","IMPORT_ONLY","SKIP"],"example":"STRICT"},"kidStrategy":{"type":"string","description":"Kid generation strategy for multi-key PKCS#12 files (AUTO or MANUAL).\nDefault: AUTO\n","enum":["AUTO","MANUAL"],"example":"AUTO"},"kidMappings":{"type":"object","additionalProperties":{"type":"string"},"description":"Manual kid mappings (alias -> kid) for multi-key imports.\nRequired only when kidStrategy=MANUAL.\n","example":{"alias1":"prod-key-1","alias2":"prod-key-2"}}},"required":["kid","p12FileBase64"]},"ImportFailure":{"type":"object","description":"Information about a key that failed to import from PKCS#12","properties":{"alias":{"type":"string","description":"PKCS#12 alias of the key that failed to import","example":"expired-signing-key"},"kid":{"type":"string","description":"Generated kid (if kid generation succeeded before failure)","example":"legacy-bundle-expired-signing-key"},"errorType":{"type":"string","description":"Error type category (EXPIRED, INVALID_CHAIN, KEY_BINDING_FAILED, etc.)","example":"EXPIRED"},"errorMessage":{"type":"string","description":"Detailed error message explaining why import failed","example":"Certificate expired on 2023-12-31T23:59:59Z (STRICT mode rejects expired certificates)"}}},"KeyExportResponse":{"type":"object","description":"Contains detailed information about an exported cryptographic key,\nincluding metadata, usage limits, and lifecycle status.\nPrivate key material is never returned here.\n","properties":{"kid":{"type":"string","description":"A unique identifier (kid) for this key in the keystore.","example":"myRsaKey"},"kty":{"type":"string","description":"The key type (kty), e.g. 'RSA', 'EC', 'oct', 'ML-KEM', 'ML-DSA', etc.","example":"RSA"},"alg":{"type":"string","description":"The algorithm associated with this key,\ne.g. 'RSA-2048', 'ES256', 'AES-256', 'ML-KEM-768'.\n","example":"RSA-2048"},"publicKey":{"type":"string","description":"The public portion of the key in Base64 (or PEM) if asymmetric.\nFor symmetric keys (kty=oct), this is usually null or empty.\n","example":"BASE64-ENCODED-PUBLIC-KEY"},"keyOps":{"type":"array","description":"A list of operations permitted on this key, e.g. ['sign', 'verify'].","example":["encrypt","decrypt"],"items":{"type":"string"}},"exportable":{"type":"boolean","description":"Indicates whether this key is exportable from the secure store.\nIf false, certain retrieval endpoints might omit additional metadata.\n","example":true},"legacy":{"type":"boolean","description":"Indicates if this key was imported from a legacy PKCS#12 file with an expired certificate.\nLegacy keys have restricted keyOps (typically decrypt and verify only).\n","example":false},"createdAt":{"type":"string","description":"The ISO 8601 date-time indicating when this key was created.","example":"2025-01-15T10:20:00Z"},"expiresAt":{"type":"string","description":"The ISO 8601 date-time after which the key is no longer valid for operations,\nif expiration is enforced.\n","example":"2030-03-02T15:00:00Z"},"softLimitExpiration":{"type":"string","description":"An optional ISO 8601 date-time for the soft-limit expiration.\nThe system may issue warnings after this point but before the hard expiration.\n","example":"2029-12-31T23:59:59Z"},"usageCount":{"type":"integer","format":"int32","description":"Tracks how many times this key has been used so far.","example":45},"lastUsedAt":{"type":"string","description":"The ISO 8601 date-time indicating the last time this key was used.","example":"2025-06-10T12:30:45Z"},"softUsageLimit":{"type":"integer","format":"int32","description":"Soft-limit usage count for the key, used to trigger warnings before\nreaching the maximum usage limit. If not set, it may default to maxUsageLimit.\n","example":40000},"maxUsageLimit":{"type":"integer","format":"int32","description":"The maximum number of usage operations permitted on this key.\nOnce this limit is reached, the key becomes invalid. A value of 0 means unlimited.\n","example":50000},"status":{"type":"string","description":"Indicates the current status of this key, e.g. 'ACTIVE', 'EXPIRED', 'REVOKED', etc.\n","example":"ACTIVE"},"nextKid":{"type":"string","description":"If this key was rotated to a new key, nextKid references that new key's identifier.\n","example":"myRsaKeyRotated"},"previousKid":{"type":"string","description":"If this key was rotated from an older key, previousKid references that older key's identifier.\n","example":"myRsaKeyOld"},"hash":{"type":"string","description":"A hash or fingerprint of the canonical subset of fields for this key,\nused to detect tampering or ensure integrity.\n","example":"F6A9B8D2..."}}},"Pkcs12ImportResponse":{"type":"object","description":"Response containing all keys imported from a PKCS#12 keystore file","properties":{"totalImported":{"type":"integer","format":"int32","description":"Total number of private keys successfully imported from the PKCS#12 file","example":2,"minimum":1},"importedKeys":{"type":"array","description":"Detailed information about each imported key (kid, kty, alg, keyOps, status, lifecycle data)","items":{"$ref":"#/components/schemas/KeyExportResponse"}},"failures":{"type":"array","description":"List of keys that failed to import (empty if all succeeded). Used for partial import scenarios.","example":[],"items":{"$ref":"#/components/schemas/ImportFailure"}},"totalTrustedCertificates":{"type":"integer","format":"int32","description":"Total number of trusted certificates (CAs) successfully imported from the PKCS#12 file","example":2,"minimum":0},"importedTrustedCertificates":{"type":"array","description":"Detailed information about each imported trusted certificate (CA)","items":{"$ref":"#/components/schemas/TrustedCertificateInfo"}},"skipped":{"$ref":"#/components/schemas/SkippedEntries","description":"Entries that were skipped because they already exist (idempotent reimports). Null if nothing was skipped."}},"required":["importedKeys","importedTrustedCertificates","totalImported","totalTrustedCertificates"]},"SkippedEntries":{"type":"object","description":"Entries that were skipped because they already exist in the keystore","properties":{"privateKeys":{"type":"array","description":"Kids of private keys that already existed and were skipped","items":{"type":"string"}},"trustedCertificates":{"type":"array","description":"Kids of trusted certificates that already existed and were skipped","items":{"type":"string"}}}},"TrustedCertificateInfo":{"type":"object","description":"Information about a trusted certificate (CA) imported from PKCS#12","properties":{"kid":{"type":"string","description":"Unique identifier (kid) assigned to this certificate in the keystore","example":"tenant-2024-trust-ca-root"},"alias":{"type":"string","description":"Original PKCS#12 alias for this certificate","example":"CA Root Certificate"},"subject":{"type":"string","description":"Subject Distinguished Name of the certificate","example":"CN=Example CA Root, O=Example Organization, C=US"},"issuer":{"type":"string","description":"Issuer Distinguished Name of the certificate","example":"CN=Example CA Root, O=Example Organization, C=US"},"serialNumber":{"type":"string","description":"Certificate serial number in hexadecimal format","example":"1A2B3C4D5E6F"},"notBefore":{"type":"string","description":"Certificate validity start date (ISO 8601)","example":"2020-01-01T00:00:00Z"},"notAfter":{"type":"string","description":"Certificate validity end date (ISO 8601)","example":"2040-01-01T00:00:00Z"},"isCACertificate":{"type":"boolean","description":"Whether this is a CA certificate (basicConstraints CA=true)","example":true},"warnings":{"type":"array","description":"Warnings about certificate state (EXPIRED, NOT_YET_VALID, SELF_SIGNED, etc.)","example":["EXPIRED"],"items":{"type":"string"}}},"required":["kid"]},"ProblemDetails":{"type":"object","description":"Standard RFC 7807 problem envelope.","properties":{"type":{"type":"string","description":"URI reference to the problem type.","example":"https://docs.ankatech.co/errors/invalid-input"},"title":{"type":"string","writeOnly":true},"status":{"type":"integer","format":"int32","description":"HTTP status code.","example":400},"detail":{"type":"string","description":"Human‑readable explanation of the error.","example":"The 'kid' field must not be blank."},"instance":{"type":"string","description":"URI reference to the specific occurrence.","example":"/api/key-management/keys"},"timestamp":{"type":"integer","format":"int64","description":"Epoch‑second timestamp of the error.","example":1745119200},"extensions":{"type":"object","additionalProperties":{},"writeOnly":true}}},"KeyImportRequest":{"type":"object","description":"Describes the parameters for importing an existing cryptographic key.\nAllows specifying publicKey/privateKey for partial or full import,\nalong with key metadata (kty, alg, keyOps, etc.).\n","properties":{"kid":{"type":"string","description":"A unique identifier (kid) for the key. If it already exists, import logic will update or conflict-check.","example":"myImportedKey","minLength":1},"kty":{"type":"string","description":"The key type, e.g. 'RSA', 'EC', 'oct', 'ML-KEM', etc.\nMust match the actual key material if present.\n","example":"EC","minLength":1},"alg":{"type":"string","description":"The algorithm for which this key is intended, e.g. 'ES256', 'AES-256', 'RSA-2048'.\nMust be consistent with kty if the material is provided.\n","example":"ES256","minLength":1},"publicKey":{"type":"string","description":"A base64-encoded or PEM-encoded public key, if applicable (asymmetric).\nFor symmetric keys (kty=oct), typically null or omitted.\n","example":"BASE64-OR-PEM-PUBLIC-KEY"},"privateKey":{"type":"string","description":"A base64-encoded or PEM-encoded private/secret key, if applicable.\nFor symmetric keys (kty=oct), this may hold the entire secret.\n","example":"BASE64-OR-PEM-PRIVATE-KEY"},"keyOps":{"type":"array","description":"A list of operations permitted on this key, e.g. ['encrypt', 'decrypt'].","example":["encrypt","decrypt"],"items":{"type":"string"}},"exportable":{"type":"boolean","description":"Indicates whether this key can be exported from the ankasecure store.","example":false},"expiresAt":{"type":"string","description":"ISO 8601 date-time after which the key is no longer valid for operations. May be null.","example":"2026-05-31T23:59:59Z"},"softLimitExpiration":{"type":"string","description":"Optional ISO 8601 date-time for the soft-limit expiration.\nMay default to 'expiresAt' if not set.\n","example":"2025-12-31T00:00:00Z"},"maxUsageLimit":{"type":"integer","format":"int32","description":"Maximum usage operations allowed. A value of 0 means unlimited.","example":10000},"softUsageLimit":{"type":"integer","format":"int32","description":"Soft-limit usage count, used for warnings. Defaults to maxUsageLimit if not provided.","example":9000}},"required":["alg","kid","kty"]},"Pkcs7ConversionRequest":{"type":"object","description":"Request for converting PKCS#7/CMS to JOSE (JWE/JWS).","properties":{"pkcs7Data":{"type":"string","description":"PKCS#7/CMS data encoded as Base64 (DER format)","example":"MIIGHgYJKoZIhvcNAQcCoIIGDzCCBgsCAQAxggE...","minLength":1},"decryptionKid":{"type":"string","description":"Optional: Key identifier for decrypting EnvelopedData.\nRequired if PKCS#7 structure is encrypted (EnvelopedData or SignedAndEnvelopedData).\nMust reference a key imported via /api/migration/pkcs12.\nSystem will validate that this key matches the PKCS#7 recipient (issuerDN + serialNumber).\n","example":"legacy-recipient-key"},"serialization":{"type":"string","default":"AUTO","description":"Output serialization mode.\n- AUTO (default): Choose Compact if 1 signer + 1 recipient, else error\n- COMPACT: Force Compact serialization (error if >1 actor)\n- JSON: Force JSON serialization (not yet available)\n","enum":["AUTO","COMPACT","JSON"],"example":"AUTO"},"targetFormat":{"type":"string","default":"AUTO","description":"Target JOSE format.\n- AUTO (default): Detect from PKCS#7 structure\n - SignedData only → JWS\n - EnvelopedData only → JWE\n - Both → JWE_JWS_NESTED\n- JWS: Force JWS output (error if PKCS#7 has encryption)\n- JWE: Force JWE output (error if PKCS#7 has signature)\n- JWE_JWS_NESTED: Force nested output (error if PKCS#7 lacks signature or encryption)\n","enum":["AUTO","JWS","JWE","JWE_JWS_NESTED"],"example":"AUTO"},"validateCertificates":{"type":"boolean","default":false,"description":"Policy flag: validate certificate chains using PKIX (default: false).\nIf true, performs full PKIX validation of embedded certificates.\nNot yet available.\n","example":false},"validateTimestamp":{"type":"boolean","default":false,"description":"Policy flag: validate RFC 3161 timestamps (default: false).\nIf true, verifies timestamp token signature and messageImprint.\nNot yet available.\n","example":false},"algorithmPolicy":{"$ref":"#/components/schemas/AlgorithmPolicy","description":"Algorithm transformation policy.\nControls how legacy PKCS#7 algorithms are upgraded to modern JOSE algorithms.\n"}},"required":["pkcs7Data"]},"AlgorithmTransformation":{"type":"object","description":"Algorithm transformation applied during conversion","properties":{"original":{"type":"string","description":"Original PKCS#7 algorithm with OID","example":"SHA256withRSA (OID: 1.2.840.113549.1.1.11)"},"transformed":{"type":"string","description":"Transformed JOSE algorithm","example":"RS256"},"reason":{"type":"string","description":"Reason for transformation","example":"Mapped to JOSE signature algorithm"}}},"DecisionMetadata":{"type":"object","description":"Metadata about conversion decisions","properties":{"signerCount":{"type":"integer","format":"int32","description":"Number of signers detected in PKCS#7","example":1},"recipientCount":{"type":"integer","format":"int32","description":"Number of recipients detected in PKCS#7","example":0},"chosenFormat":{"type":"string","description":"Target format chosen (AUTO mode decision)","example":"JWS"},"chosenSerialization":{"type":"string","description":"Serialization chosen (AUTO mode decision)","example":"COMPACT"},"reason":{"type":"string","description":"Explanation of why this format was chosen","example":"Single signer detected (no encryption), using JWS Compact serialization"}}},"Pkcs7ConversionResponse":{"type":"object","description":"Response containing converted JOSE token with conversion metadata.","properties":{"joseToken":{"description":"Converted JOSE token.\n- For Compact serialization: String (JWS/JWE Compact)\n- For JSON serialization: Object (JWS/JWE General JSON) [not yet available]\n","example":"eyJraWQiOiJsZWdhY3lTaWduZXIiLCJhbGciOiJSUzI1NiJ9.SGVsbG8gV29ybGQ.signature...","oneOf":[{"type":"string"},{}]},"serialization":{"type":"string","description":"Serialization mode used","enum":["COMPACT","JSON"],"example":"COMPACT"},"structure":{"type":"string","description":"JOSE structure type","enum":["JWS","JWE","JWE_JWS_NESTED"],"example":"JWS"},"decision":{"$ref":"#/components/schemas/DecisionMetadata","description":"Decision metadata explaining auto-selection logic"},"signers":{"type":"array","description":"Signer conversion results","items":{"$ref":"#/components/schemas/SignerConversionResult"}},"recipients":{"type":"array","description":"Recipient conversion results","items":{"$ref":"#/components/schemas/RecipientConversionResult"}},"algorithmTransformations":{"type":"array","description":"Algorithm transformations applied during conversion","items":{"$ref":"#/components/schemas/AlgorithmTransformation"}},"warnings":{"type":"array","description":"Warnings about conversion process","items":{"type":"string"}}},"required":["joseToken","serialization","structure"]},"RecipientConversionResult":{"type":"object","description":"Recipient conversion result","properties":{"originalIssuerDN":{"type":"string","description":"Original issuer DN from PKCS#7 RecipientInfo","example":"CN=Example Recipient, O=Example Organization, C=US"},"originalSerialNumber":{"type":"string","description":"Original serial number from PKCS#7 RecipientInfo","example":"0x9F8E7D6C5B4A3B2C"},"assignedKid":{"type":"string","description":"KID assigned to this recipient (user-specified or matched)","example":"legacy-recipient-key"},"algorithm":{"type":"string","description":"JOSE algorithm used for key encryption","example":"RSA-OAEP"},"warnings":{"type":"array","description":"Warnings specific to this recipient","items":{"type":"string"}}},"required":["assignedKid"]},"SignerConversionResult":{"type":"object","description":"Signer conversion result","properties":{"originalIssuerDN":{"type":"string","description":"Original issuer DN from PKCS#7 SignerInfo","example":"CN=Example Signer, O=Example Organization, C=US"},"originalSerialNumber":{"type":"string","description":"Original serial number from PKCS#7 SignerInfo","example":"0x4A3F2E1D5B6C7A8B"},"assignedKid":{"type":"string","description":"KID assigned to this signer (matched from imported keys)","example":"legacySignerKey"},"algorithm":{"type":"string","description":"JOSE algorithm used for signature","example":"RS256"},"certificateMatched":{"type":"boolean","description":"Whether original PKCS#7 certificate was already imported in keystore","example":true},"warnings":{"type":"array","description":"Warnings specific to this signer","items":{"type":"string"}}},"required":["assignedKid"]},"Pkcs7AnalysisRequest":{"type":"object","description":"Request for analyzing PKCS#7/CMS file structure and extracting metadata.","properties":{"pkcs7Data":{"type":"string","description":"PKCS#7/CMS data encoded as Base64 (DER format)","example":"MIIGHgYJKoZIhvcNAQcDoIIGDzCCBgsCAQAxggE...","minLength":1},"decryptionKid":{"type":"string","description":"Optional key identifier for decrypting EnvelopedData to analyze inner SignedData.\nRequired only if the PKCS#7 structure is encrypted and inner content analysis is needed.\nMust reference a key imported via /api/migration/private-keys.\n","example":"legacy-rsa-key"},"validateCertificates":{"type":"boolean","default":false,"description":"Policy flag: validate certificate chains using PKIX (default: false).\nIf true, performs full certificate chain validation including:\n- Validity period checks (notBefore/notAfter)\n- KeyUsage extension validation\n- CRL/OCSP revocation checking (if available)\n","example":false},"validateTimestamp":{"type":"boolean","default":false,"description":"Policy flag: validate RFC 3161 timestamps (default: false).\nIf true, verifies timestamp token signature and messageImprint.\nNot yet available.\n","example":false}},"required":["pkcs7Data"]},"KeyGenerationRequest":{"type":"object","description":"Describes the parameters for generating a new cryptographic key.\nSupports classical (RSA, EC), symmetric (oct), and post-quantum (ML-KEM, ML-DSA, etc.)\nalgorithms.\nOmitted fields like 'softUsageLimit' may default to 'maxUsageLimit'.\n","properties":{"kid":{"type":"string","description":"A unique identifier (kid) to assign to this newly generated key.","example":"myNewKeyId","minLength":1},"kty":{"type":"string","description":"Key type (kty), e.g. 'oct', 'RSA', 'EC', 'ML-KEM', 'ML-DSA', 'FALCON', 'SLH-DSA'.\nRefer to GET /api/key-management/supported-algorithms for valid values.\n","example":"oct","minLength":1},"alg":{"type":"string","description":"Algorithm name or parameter set. Examples: 'AES-256', 'RSA-2048',\n'EC-256', 'ML-KEM-768', etc.\nRefer to GET /api/key-management/supported-algorithms for valid values.\n","example":"AES-256","minLength":1},"keyOps":{"type":"array","description":"List of permitted operations on this key, e.g. ['encrypt','decrypt'].","example":["encrypt","decrypt"],"items":{"type":"string"}},"exportable":{"type":"boolean","description":"Indicates whether this key can be exported from ankasecure storage.","example":true},"expiresAt":{"type":"string","description":"ISO 8601 date-time at which the key expires.\nIf omitted, a far-future default (like 100 years) may be used.\n","example":"2030-01-15T00:00:00Z"},"softLimitExpiration":{"type":"string","description":"ISO 8601 date-time for a soft-limit expiration.\nThe system may issue warnings after this point but before 'expiresAt'.\nIf omitted, may default to 'expiresAt'.\n","example":"2029-12-31T23:59:59Z"},"maxUsageLimit":{"type":"integer","format":"int32","description":"Maximum number of usage operations permitted on this key.\nA value of 0 means unlimited.\n","example":5000},"softUsageLimit":{"type":"integer","format":"int32","description":"Soft-limit usage count for the key. If omitted, the system may set it\nequal to 'maxUsageLimit'.\n","example":4000}},"required":["alg","kid","kty"]},"KeySummaryResponse":{"type":"object","description":"Minimal key metadata returned by the\nlistKeys endpoint. It is safe to expose in bulk responses\nbecause it contains no cryptographic material.\n","properties":{"kid":{"type":"string","description":"Unique key identifier (kid).","example":"myRsaKey"},"uuid":{"type":"string","description":"Global unique identifier (UUID) for the key.","example":"550e8400-e29b-41d4-a716-446655440000"},"type":{"type":"string","description":"Key type: SIMPLE (single algorithm) or COMPOSITE (hybrid).","example":"SIMPLE"},"compositeMode":{"type":"string","description":"Composite mode for hybrid keys (only when type=COMPOSITE).","example":"HYBRID_KEM_COMBINE"},"kty":{"type":"string","description":"Key family (kty), e.g. RSA, ML-KEM, oct. For composite keys, this may be null.","example":"RSA"},"alg":{"type":"string","description":"Concrete algorithm / parameter-set.","example":"RSA-2048"},"status":{"type":"string","description":"Lifecycle state (ACTIVE, ROTATED, EXPIRED, REVOKED, …).","example":"ACTIVE"},"createdAt":{"type":"string","description":"ISO-8601 UTC creation time.","example":"2025-01-15T10:20:00Z"},"expiresAt":{"type":"string","description":"Hard expiration time (UTC) or null.","example":"2030-01-15T10:20:00Z"},"softLimitExpiration":{"type":"string","description":"Soft-limit expiration time (UTC) or null.","example":"2029-07-15T10:20:00Z"},"usageCount":{"type":"integer","format":"int32","description":"Current usage counter.","example":1243},"softUsageLimit":{"type":"integer","format":"int32","description":"Soft usage limit or null.","example":900000},"maxUsageLimit":{"type":"integer","format":"int32","description":"Hard usage limit (0/null = unlimited).","example":1000000},"exportable":{"type":"boolean","description":"Whether the key is exportable.","example":true},"keyOps":{"type":"array","description":"List of cryptographic operations permitted on this key (immutable).","example":["encrypt","decrypt"],"items":{"type":"string"}},"legacy":{"type":"boolean","description":"Indicates if key was imported from legacy PKCS#12 with expired certificate.","example":false},"hash":{"type":"string","description":"SHA-256 fingerprint of canonical key fields for integrity verification.","example":"F6A9B8D2E4C1A7F3B9D8E2A4C6F1B3D5E7A9C2F4B6D8E1A3C5F7B9D2E4A6C8F1"},"nextKid":{"type":"string","description":"Identifier of the successor key, if rotated."},"previousKid":{"type":"string","description":"Identifier of the predecessor key, if rotated."}}},"RotationRequest":{"type":"object","description":"Parameters for an immediate key rotation.","properties":{"newKey":{"$ref":"#/components/schemas/KeyGenerationRequest","description":"Descriptor for the successor key."}},"required":["newKey"]},"ComponentSpec":{"type":"object","description":"Specification for a component algorithm within a composite key.\nEach composite key must have exactly one classical component and one PQC component.\n","properties":{"role":{"type":"string","description":"Component role: 'classical' for traditional algorithms, 'pqc' for post-quantum algorithms.","enum":["classical","pqc"],"example":"classical","minLength":1},"algorithm":{"type":"string","description":"Cryptographic algorithm identifier for this component:\n- Classical KEM (HYBRID_KEM_COMBINE): X25519, RSA-3072, RSA-4096\n- PQC KEM (HYBRID_KEM_COMBINE): ML-KEM-768, ML-KEM-1024\n- Classical signature (DUALSIGN): Ed25519, ECDSA-P256, ECDSA-P384\n- PQC signature (DUALSIGN): ML-DSA-44, ML-DSA-65, ML-DSA-87\n","example":"X25519","minLength":1}},"required":["algorithm","role"]},"CompositeKeyRequest":{"type":"object","description":"Request for generating a composite hybrid key combining classical and post-quantum cryptographic algorithms. Supports HYBRID_KEM_COMBINE mode for quantum-resistant encryption (AND-decrypt) and DUALSIGN mode for dual signatures with configurable verification policies.\n","properties":{"kid":{"type":"string","description":"Unique key identifier (kid). Must be unique within the tenant keystore.","example":"hybrid-kem-production-001","minLength":1},"mode":{"type":"string","description":"Composite mode determining cryptographic operation semantics:\n- HYBRID_KEM_COMBINE: Hybrid KEM with HKDF secret combination (AND-decrypt). Requires BOTH classical and PQC secrets to decrypt.\n- DUALSIGN: Dual signatures with configurable verification policy. Generates two independent signatures (classical + PQC).\n","enum":["HYBRID_KEM_COMBINE","DUALSIGN"],"example":"HYBRID_KEM_COMBINE"},"componentAlgorithms":{"type":"array","description":"List of component algorithm specifications. Must contain exactly 2 components:\none classical and one PQC. Valid combinations depend on mode:\n- HYBRID_KEM_COMBINE: X25519/RSA-3072/RSA-4096 + ML-KEM-768/ML-KEM-1024\n- DUALSIGN: Ed25519/ECDSA-P256/ECDSA-P384 + ML-DSA-44/ML-DSA-65/ML-DSA-87\n","items":{"$ref":"#/components/schemas/ComponentSpec"},"minItems":1},"kdf":{"type":"string","default":"HKDF-SHA256","description":"Key Derivation Function for HYBRID_KEM_COMBINE mode. Only HKDF-SHA256 is supported. Ignored for DUALSIGN mode.","example":"HKDF-SHA256"},"verificationPolicy":{"type":"string","default":"ALL","description":"Verification policy for DUALSIGN mode (ignored for HYBRID_KEM_COMBINE):\n- ALL: Both signatures must verify (strictest, recommended)\n- ANY: At least one signature must verify\n- CLASSICAL_REQUIRED: Classical required, PQC optional\n- PQC_REQUIRED: PQC required, classical optional\n","enum":["ALL","ANY","CLASSICAL_REQUIRED","PQC_REQUIRED"],"example":"ALL"},"keyOps":{"type":"array","description":"Allowed key operations. If not specified, auto-derived from mode:\n- HYBRID_KEM_COMBINE → [\"encrypt\", \"decrypt\"]\n- DUALSIGN → [\"sign\", \"verify\"]\n","example":["encrypt","decrypt"],"items":{"type":"string"}},"expiresAt":{"type":"string","description":"Hard expiration date in ISO-8601 UTC format. After this date, key becomes unusable.","example":"2030-12-31T23:59:59Z"},"maxUsageLimit":{"type":"integer","format":"int32","description":"Maximum number of cryptographic operations allowed. 0 or null means unlimited.","example":1000000},"softUsageLimit":{"type":"integer","format":"int32","description":"Soft usage limit (warning threshold). When reached, warnings are logged but operations continue. Must be < maxUsageLimit.","example":800000},"softLimitExpiration":{"type":"string","description":"Soft expiration date (warning threshold) in ISO-8601 UTC format. When reached, warnings are logged but key remains usable. Must be < expiresAt.","example":"2029-12-31T23:59:59Z"},"exportable":{"type":"boolean","default":false,"description":"Whether the public key material can be exported via migration endpoints.","example":false}},"required":["componentAlgorithms","kid","mode"]},"SignatureUtilityApi":{"type":"object","description":"Detached JWS (+ pub-key) as JSON part","properties":{"kty":{"type":"string","description":"Key type (kty) for the signature, e.g. 'RSA', 'EC', 'ML-DSA'.\nMust match the actual algorithm and publicKey used.\n","example":"ML-DSA","minLength":1},"alg":{"type":"string","description":"Algorithm name or parameter set, e.g. 'RSA-2048', 'ML-DSA-87'.\nMust be consistent with the kty if the publicKey is provided.\n","example":"ML-DSA-87","minLength":1},"publicKey":{"type":"string","description":"Base64-encoded public key, required for signature verification of asymmetric keys.","example":"BASE64-ENCODED-PUBLIC-KEY"},"signatureBase64":{"type":"string","description":"Base64-encoded digital signature to be verified under the specified kty/alg/publicKey.","example":"BASE64-SIGNATURE-DATA"}},"required":["alg","kty"]},"VerifySignatureResponse":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether the signature matches the supplied data."},"keyRequested":{"type":"string","description":"kid sent by the client (from the JWS header)."},"actualKeyUsed":{"type":"string","description":"kid actually used for verification (after rotation)."},"algorithmUsed":{"type":"string","description":"Signature algorithm (from JWS header)."},"warnings":{"type":"array","description":"Non-critical warnings (usage limits, expiry, …).","items":{"type":"string"}}},"required":["valid"]},"CryptoUtilityApi":{"type":"object","description":"JSON metadata with the public‑key.","properties":{"kty":{"type":"string","description":"Key type, e.g. 'oct', 'RSA', 'EC', 'ML-KEM', 'ML-DSA', 'FALCON', 'SLH-DSA'.\nFor a dynamic list of currently supported kty values, see:\nGET /api/key-management/supported-algorithms.\n","example":"ML-KEM","minLength":1},"alg":{"type":"string","description":"Algorithm name, e.g. 'A256GCM', 'RSA-2048', 'ML-KEM-768'.\nFor a dynamic list of currently supported algorithms, see:\nGET /api/key-management/supported-algorithms.\n","example":"ML-KEM-1024","minLength":1},"publicKey":{"type":"string","description":"Base64-encoded public key bytes, for asymmetric keys.","example":"BASE64-ENCODED-PUBLIC-KEY"}},"required":["alg","kty"]},"VerifyJwsRequest":{"type":"object","description":"Request object for verifying a JWS (Compact Serialization).","properties":{"jws":{"type":"string","description":"The compact JWS string to be verified.","minLength":1}},"required":["jws"]},"VerifyDetachedJwsStreamRequest":{"type":"object","description":"JSON wrapper that carries the detached-JWS produced by\n/stream/sign.\n","properties":{"detachedJws":{"type":"string","description":"Detached JWS (General-JSON) whose payload is detached.","example":{"protected":"eyJhbGciOiJNSy1EU0EtNzc4Iiwia2lkIjoibXlQa3lJZCJ9","signature":null},"minLength":1}},"required":["detachedJws"]},"SignStreamRequest":{"type":"object","description":"JSON metadata sent with multipart sign requests.","properties":{"kid":{"type":"string","description":"Private-key identifier (kid) that signs the payload.","example":"myPrivateKid","minLength":1}},"required":["kid"]},"CryptoPolicyInfo":{"type":"object","description":"Decoded payload of the **Crypto-Policy-Info** header.","properties":{"current_key_requested":{"type":"string","description":"kid as present in the incoming request header"},"current_key_used":{"type":"string","description":"kid actually used after rotation lookup"},"current_key_algorithm":{"type":"string","description":"Algorithm used with the current key"},"current_key_exp_warn_days":{"type":"integer","format":"int32","description":"Days until hard expiry of the current key (0 = none)"},"current_key_usage_warn":{"type":"integer","format":"int32","description":"Invocations remaining until the current key’s hard usage limit (0 = none)"},"new_key_requested":{"type":"string","description":"kid supplied via the newKid parameter"},"new_key_used":{"type":"string","description":"kid actually used for the new cryptographic operation"},"new_key_algorithm":{"type":"string","description":"Algorithm used with the new key"},"new_key_exp_warn_days":{"type":"integer","format":"int32","description":"Days until hard expiry of the new key (0 = none)"},"new_key_usage_warn":{"type":"integer","format":"int32","description":"Invocations remaining until the new key’s hard usage limit (0 = none)"},"migration_mode":{"type":"boolean","description":"true when sourceKidOverride was applied"}}},"ResignDetachedJwsStreamRequest":{"type":"object","description":"JSON metadata sent in the metadata field when streaming a\nre-sign request. Carries the existing detached JWS, the new signing key,\nand an optional override for a missing header kid.\n","properties":{"oldJws":{"type":"string","description":"Detached JWS (General-JSON) produced earlier by /sign.","example":{"protected":"eyJhbGciOiJNSy1EU0EtNzc4Iiwia2lkIjoib2xkS2lkIn0","signature":null},"minLength":1},"newKid":{"type":"string","description":"Public-key identifier (kid) that will sign the new JWS.","example":"myNewSignKid","minLength":1},"sourceKidOverride":{"type":"string","description":"Optional fallback key ID to use when the incoming JWS header lacks a kid.","example":"legacySignKeyV1"}},"required":["newKid","oldJws"]},"JwetGeneralJsonHeaderReencrypt":{"type":"object","description":"JWE header in General-JSON serialization.\n\n• **Managed flow ** – if `recipients[0].header.kid`\n is present, that kid is used as the decryption key.\n\n• **Migration flow ** – when the header lacks a kid\n (legacy ciphertext) the caller **must** supply\n `sourceKidOverride`.\n","properties":{"protected":{"type":"string","description":"Base64url-encoded protected header."},"iv":{"type":"string","description":"Base64url-encoded IV of the AEAD algorithm."},"ciphertext":{"type":"string","description":"Detached ciphertext – always {@code null} here."},"tag":{"type":"string","description":"Detached authentication tag – always {@code null} here."},"recipients":{"type":"array","description":"Exactly one recipient (kid intentionally absent).","items":{"$ref":"#/components/schemas/RecipientLegacy"}}},"required":["iv","protected","recipients"]},"RecipientHeaderLegacy":{"type":"object","properties":{"kid":{"type":"string","description":"Key identifier (kid) MUST be absent in legacy flows."},"alg":{"type":"string","description":"Key-encapsulation / wrap algorithm (e.g. RSA-OAEP-512)."}},"required":["alg"]},"RecipientLegacy":{"type":"object","properties":{"header":{"$ref":"#/components/schemas/RecipientHeaderLegacy","description":"Per-recipient header (kid omitted)."},"encrypted_key":{"type":"string","description":"Base64url-encoded encrypted key for this recipient."}},"required":["encrypted_key","header"]},"EncryptStreamRequest":{"type":"object","description":"Metadata for the streaming encryption endpoint.","properties":{"kid":{"type":"string","description":"Public-key identifier (kid) that will receive the CEK.","example":"myPublicKid","minLength":1}},"required":["kid"]},"JwetGeneralJsonHeaderDecrypt":{"type":"object","description":"JWET header (General-JSON).","properties":{"protected":{"type":"string","description":"Base64url-encoded protected header."},"iv":{"type":"string","description":"Base64url-encoded IV of the AEAD algorithm."},"ciphertext":{"type":"string","description":"Detached ciphertext – always {@code null} here."},"tag":{"type":"string","description":"Detached authentication tag – always {@code null} here."},"recipients":{"type":"array","description":"Exactly one recipient describing the wrapped CEK.","items":{"$ref":"#/components/schemas/RecipientManaged"}}},"required":["iv","protected","recipients"]},"RecipientHeaderManaged":{"type":"object","properties":{"kid":{"type":"string","description":"Key identifier (kid)."},"alg":{"type":"string","description":"Key-encapsulation / wrap algorithm (e.g. ML-KEM-768)."}},"required":["alg","kid"]},"RecipientManaged":{"type":"object","properties":{"header":{"$ref":"#/components/schemas/RecipientHeaderManaged","description":"Per-recipient header (kid mandatory)."},"encrypted_key":{"type":"string","description":"Base64url-encoded encrypted key for this recipient."}},"required":["encrypted_key","header"]},"SignRequest":{"type":"object","description":"Request object for signing Base64-encoded data with optional timestamp and expiration.","properties":{"kid":{"type":"string","description":"The kid of the private key used to sign the data.","example":"mySigningKeyKid","minLength":1},"data":{"type":"string","description":"The raw data in Base64 to be signed.","example":"U2lnblRoaXNEYXRh","minLength":1},"validityDays":{"type":"integer","format":"int64","description":"Optional validity period in days for the signature. If not specified, the signature will not expire.","example":365,"maximum":3650,"minimum":1}},"required":["data","kid"]},"SignJwsResponse":{"type":"object","description":"JWS signature response with polymorphic format support.\n\nResponse Content-Type:\n• application/jose (SIMPLE keys, compact format)\n• application/jose+json (COMPOSITE keys, general JSON)\n","properties":{"jwsToken":{"description":"JWS token in either Compact (String) or General JSON (Object) format.\n\nSIMPLE keys: RFC 7515 Compact Serialization (String)\nExample: \"eyJraWQi.payload.signature\"\n\nCOMPOSITE keys: RFC 7515 General JSON Serialization (Map)\nExample: {\"payload\":\"...\",\"signatures\":[{\"protected\":\"...\",\"signature\":\"...\"},...]}\n\nClient detects format via Content-Type header:\n- application/jose = String (compact)\n- application/jose+json = Object (general JSON)\n","example":"eyJraWQiOiJteS1raWQiLCJhbGciOiJQUzI1NiJ9.SGVsbG8gSm9zZQ.Y2E5M2Y0ZDVmNzA4ZmYzZGM3ZDAxZjY1N2YwN2U3ZDVkMTMxZjI2ODg3ZmMwNmI0"},"keyRequested":{"type":"string","description":"Key identifier requested by the client.","example":"mySigningKeyKid"},"actualKeyUsed":{"type":"string","description":"Key identifier effectively used (after rotation).","example":"mySigningKeyKid_v2"},"algorithmUsed":{"type":"string","description":"JWS algorithm effectively used (e.g. PS256, ML-DSA-87).","example":"ML-DSA-87"},"warnings":{"type":"array","description":"Optional warnings (usage counters, sunset notices, …).","items":{"type":"string"}}}},"SignEncryptRequest":{"type":"object","description":"Request for sign-then-encrypt operation producing nested JWE(JWS).","properties":{"data":{"type":"string","description":"Base64-encoded data to sign and encrypt","example":"SGVsbG8gQW5rYQ==","minLength":1},"signKid":{"type":"string","description":"Key identifier for signing operation","example":"mySigningKey","minLength":1},"encryptKid":{"type":"string","description":"Key identifier for encryption operation","example":"myEncryptionKey","minLength":1},"validityDays":{"type":"integer","format":"int64","description":"Optional validity period in days for the signature (JWS exp claim)","example":365,"maximum":3650,"minimum":1}},"required":["data","encryptKid","signKid"]},"SignEncryptResponse":{"type":"object","description":"Response containing nested JWE(JWS) token with separated metadata for sign and encrypt operations.","properties":{"jweToken":{"type":"string","description":"Nested JWE token containing signed JWS payload (RFC 7516 compact serialization)","example":"eyJraWQiOiJlbmNLZXkiLCJhbGciOiJNTC1LRU0tMTAyNCIsImVuYyI6IkEyNTZHQ00iLCJjdHkiOiJKV1MifQ..."},"signKeyRequested":{"type":"string","description":"Signing key identifier requested by client","example":"mySignKey"},"actualSignKeyUsed":{"type":"string","description":"Signing key identifier actually used (after rotation)","example":"mySignKey_v2"},"signAlgorithmUsed":{"type":"string","description":"Signing algorithm used","example":"ML-DSA-87"},"signWarnings":{"type":"array","description":"Warnings from signing operation","items":{"type":"string"}},"encryptionKeyRequested":{"type":"string","description":"Encryption key identifier requested by client","example":"myEncKey"},"actualEncryptionKeyUsed":{"type":"string","description":"Encryption key identifier actually used (after rotation)","example":"myEncKey_v2"},"encryptionAlgorithmUsed":{"type":"string","description":"Encryption algorithm used","example":"ML-KEM-1024+A256GCM"},"encryptionWarnings":{"type":"array","description":"Warnings from encryption operation","items":{"type":"string"}}},"required":["jweToken"]},"ResignJwsRequest":{"type":"object","description":"Request to verify an existing Compact JWS under oldKid\n(embedded in the header) and sign the same payload\nwith newKid. An optional sourceKidOverride\nmay be provided if the original JWS header does not specify a kid.\n","properties":{"jwsToken":{"type":"string","description":"Compact JWS signed with oldKid (embedded in header).","example":"eyJraWQiOiJvbGRLaWQiLCJhbGciOiJESUwxLXAyNTYifQ.e30.PQ…","minLength":1},"newKid":{"type":"string","description":"kid of the private key that must produce the new signature.","example":"myNewSigningKid","minLength":1},"sourceKidOverride":{"type":"string","description":"Optional fallback key ID to use when the incoming\nJWS header does not include a kid.\n","example":"legacySignKeyV1"}},"required":["jwsToken","newKid","sourceKidOverride"]},"ResignJwsResponse":{"type":"object","description":"Response produced by the JWS re-sign operation.\njwsToken is the Compact JWS signed with\nnewKid. Remaining fields mirror the HTTP headers\nemitted by the streaming variant.\n","properties":{"jwsToken":{"description":"Re-signed JWS (String for SIMPLE keys, Map for COMPOSITE keys).","example":"eyJraWQiOiJuZXdLaWQiLCJhbGciOiJESUwxLXAzODgifQ.e30.4p…"},"oldKeyRequested":{"type":"string","description":"kid that was requested for verification."},"oldKeyUsed":{"type":"string","description":"Effective kid used for verification (after rotation)."},"oldKeyAlgorithmUsed":{"type":"string","description":"Algorithm used for verification."},"newKeyRequested":{"type":"string","description":"kid that was requested for signing."},"newKeyUsed":{"type":"string","description":"Effective kid used for signing (after rotation)."},"newKeyAlgorithmUsed":{"type":"string","description":"Algorithm used for the new signature."},"warnings":{"type":"array","description":"Non-fatal warnings (usage limits, expiry…).","items":{"type":"string"}},"migrationMode":{"type":"boolean","description":"true if the service applied sourceKidOverride because\nthe incoming JWS header lacked a kid. Absent otherwise.\n","example":true}}},"ReencryptJweRequest":{"type":"object","description":"Request body for Compact-JWE re-encryption, with optional fallback for missing header KID.","properties":{"jweToken":{"type":"string","description":"Compact JWE string originally encrypted for the source key.","example":"eyJraWQiOiJvbGRLaWQiLCJhbGciOiJSQXEtT0FFUC0yNTYiLCJjdHkiOiJhcHBsaWNhdGlvbi9vY3RldC1zdHJlYW0ifQ..EnvelopedKey.iv.ciphertext.tag","minLength":1},"newKid":{"type":"string","description":"Key ID of the public key that will protect the new JWE.","example":"myNewMlkemKid","minLength":1},"sourceKidOverride":{"type":"string","description":"Optional fallback key ID to decrypt when the incoming JWE header has no kid.","example":"legacyRsaKey"}},"required":["jweToken","newKid","sourceKidOverride"]},"ReencryptJweResponse":{"type":"object","description":"Result object returned after Compact-JWE re-encryption.","properties":{"jweToken":{"description":"Re-encrypted JWE (String for SIMPLE keys, Map for COMPOSITE keys).","example":"eyJraWQiOiJuZXdLaWQiLCJhbGciOiJNTC1LRU0tMTAyNCIsImN0eSI6ImFwcGxpY2F0aW9uL29jdGV0LXN0cmVhbSJ9..NewEnvelopedKey.iv.ciphertext.tag"},"oldKeyRequested":{"type":"string","description":"kid extracted from the *incoming* JWE header.","example":"oldKid_v1"},"oldKeyUsed":{"type":"string","description":"Effective kid used for decryption (after rotation).","example":"oldKid_v2"},"oldKeyAlgorithmUsed":{"type":"string","description":"Algorithm of the key used for decryption.","example":"RSA-2048"},"newKeyRequested":{"type":"string","description":"kid requested by the caller for encryption.","example":"myNewMlkemKid"},"newKeyUsed":{"type":"string","description":"Effective kid used for encryption (after rotation).","example":"myNewMlkemKid"},"newKeyAlgorithmUsed":{"type":"string","description":"Algorithm of the key used for encryption.","example":"ML-KEM-1024"},"warnings":{"type":"array","description":"Aggregated warning messages (usage limit, expiry…).","items":{"type":"string"}},"errorMessage":{"type":"string","description":"Set only when the operation failed partially."},"migrationMode":{"type":"boolean","description":"true if the service applied sourceKidOverride because the\nincoming JWE header lacked a kid. Will be absent otherwise.\n","example":true}}},"EncryptRequest":{"type":"object","description":"Request object for encrypting Base64-encoded data.","properties":{"kid":{"type":"string","description":"The kid of the key used to encrypt the data.","example":"myKeyKid","minLength":1},"data":{"type":"string","description":"The raw data in Base64 format to be encrypted.","example":"SGVsbG8gQW5rYQ==","minLength":1}},"required":["data","kid"]},"EncryptJweResponse":{"type":"object","description":"Result object returned by the /encrypt endpoint.\n\n• jweToken contains either Compact JWE (String) for SIMPLE keys\n or JWE General JSON (Object) for COMPOSITE keys.\n• keyRequested echoes the kid originally\n supplied by the caller.\n• actualKeyUsed shows the effective key after rotation\n handling.\n• algorithmUsed is the precise algorithm negotiated by the\n crypto-engine (e.g. RSA-OAEP-512,\n ML-KEM-512, HYBRID-KEM-COMBINE).\n• warnings lists any non-fatal issues (soft usage limit,\n impending expiry, etc.).\n\nResponse Content-Type:\n• application/jose (SIMPLE keys, compact format)\n• application/jose+json (COMPOSITE keys, general JSON)\n","properties":{"jweToken":{"description":"JWE token in either Compact (String) or General JSON (Object) format.\n\nSIMPLE keys: RFC 7516 Compact Serialization (String)\nExample: \"eyJraWQi...\"\n\nCOMPOSITE keys: RFC 7516 General JSON Serialization (Map)\nExample: {\"protected\":\"...\",\"recipients\":[...],\"iv\":\"...\",\"ciphertext\":\"...\",\"tag\":\"...\"}\n\nClient detects format via Content-Type header:\n- application/jose = String (compact)\n- application/jose+json = Object (general JSON)\n","example":"eyJraWQiOiJ..."},"keyRequested":{"type":"string","description":"Key identifier that the client requested.","example":"my_original_kid"},"actualKeyUsed":{"type":"string","description":"Key identifier that was actually used after the server applied\nrotation / successor look-ups.\n","example":"my_rotated_kid_v2"},"algorithmUsed":{"type":"string","description":"Algorithm effectively employed for the encryption step, combining\nkey-encryption and content-encryption (e.g. “ML-KEM-1024+A256GCM”).\n","example":"RSA-OAEP-512+A256GCM"},"warnings":{"type":"array","description":"Optional list of warnings (soft expiry, usage quota, …).","items":{"type":"string"}}},"required":["actualKeyUsed","algorithmUsed","jweToken","keyRequested","warnings"]},"DecryptJweRequest":{"type":"object","description":"Request body for decrypting JWE in Compact or General JSON format.\nThe token already contains the kid, key-encryption\nalgorithm (alg), content-encryption algorithm\n(enc) and all cryptographic parameters (IV, CEK,\nciphertext, authentication tag); therefore no\nadditional fields are required.\n\nSupports both SIMPLE keys (String/Compact) and COMPOSITE keys (Map/General JSON).\n","properties":{"jweToken":{"description":"RFC 7516 JWE to be decrypted.\n- SIMPLE keys: String (Compact format)\n- COMPOSITE keys: Map (General JSON format)\n","example":"eyJraWQiOiJteUtleUtpZCIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJSQXEtT0FFUC0yNTYiLCJjdHkiOiJhcHBsaWNhdGlvbi9vY3RldC1zdHJlYW0ifQ..vUWhGqCHG2jc-tMc.Kut2XDEyqMvu8Q.YWmUX9yrPq5R6w"}}},"DecryptResponse":{"type":"object","description":"Response containing decrypted data or an error message.","properties":{"decryptedData":{"type":"string","description":"The decrypted data in Base64 format."},"errorMessage":{"type":"string","description":"An error message if the decryption failed."},"keyRequested":{"type":"string","description":"The key identifier requested by the client."},"actualKeyUsed":{"type":"string","description":"The actual key identifier used if rotation or other changes occurred."},"algorithmUsed":{"type":"string","description":"The algorithm actually used for decryption (e.g., ML-KEM-768)."},"warnings":{"type":"array","description":"A list of warning messages (e.g., usage limit, key expired).","items":{"type":"string"}}}},"DecryptVerifyRequest":{"type":"object","description":"Request for decrypt-then-verify operation to unwrap nested JWE(JWS).","properties":{"jweToken":{"type":"string","description":"Nested JWE token containing signed JWS payload","example":"eyJraWQiOiJlbmNLZXkiLCJhbGciOiJNTC1LRU0tMTAyNCIsImVuYyI6IkEyNTZHQ00iLCJjdHkiOiJKV1MifQ...","minLength":1},"decryptKid":{"type":"string","description":"Key identifier for decryption operation","example":"myDecryptionKey","minLength":1},"verifyKid":{"type":"string","description":"Key identifier for signature verification operation","example":"myVerificationKey","minLength":1}},"required":["decryptKid","jweToken","verifyKid"]},"DecryptVerifyResponse":{"type":"object","description":"Response from decrypt-then-verify operation with separated metadata for decrypt and verify operations.","properties":{"data":{"type":"string","description":"Base64-encoded decrypted and verified plaintext data","example":"SGVsbG8gQW5rYQ=="},"decryptKeyRequested":{"type":"string","description":"Decryption key identifier requested by client","example":"myDecryptKey"},"actualDecryptKeyUsed":{"type":"string","description":"Decryption key identifier actually used (after rotation)","example":"myDecryptKey_v2"},"decryptAlgorithmUsed":{"type":"string","description":"Decryption algorithm used","example":"ML-KEM-1024+A256GCM"},"decryptWarnings":{"type":"array","description":"Warnings from decryption operation","items":{"type":"string"}},"verifyKeyRequested":{"type":"string","description":"Verification key identifier requested by client","example":"myVerifyKey"},"actualVerifyKeyUsed":{"type":"string","description":"Verification key identifier actually used (after rotation)","example":"myVerifyKey_v2"},"verifyAlgorithmUsed":{"type":"string","description":"Verification algorithm used","example":"ML-DSA-87"},"verifyWarnings":{"type":"array","description":"Warnings from verification operation","items":{"type":"string"}}},"required":["data"]},"JsonNode":{},"LicenseValidationMetrics":{"type":"object","properties":{"unvalidatedRequestsAllowed":{"type":"integer","format":"int32"},"strictlyValidatedRequests":{"type":"integer","format":"int32"},"uniqueClients":{"type":"integer","format":"int32"},"validationRate":{"type":"number","format":"double"}}},"SupportedAlgorithm":{"type":"object","description":"Describes an algorithm profile supported by the platform.","properties":{"kty":{"type":"string"},"alg":{"type":"string"},"keyOps":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["RECOMMENDED","LEGACY"]},"sunsetDate":{"type":"string","format":"date"},"advisory":{"type":"string"},"securityLevel":{"type":"integer","format":"int32","description":"Numeric security assurance level as defined by NIST.","example":3},"standards":{"type":"array","description":"List of ratified cryptographic standards endorsing this algorithm.","example":["NIST","ETSI"],"items":{"type":"string"}},"category":{"type":"string","description":"Category of the algorithm: CLASSICAL or POST_QUANTUM.","enum":["CLASSICAL","POST_QUANTUM"],"example":"POST_QUANTUM"}},"required":["alg","keyOps","kty","status"]},"ListKeysResponse":{"type":"object","description":" Response model for listing cryptographic keys in short or extended form.\n Each key is summarized in a KeySummaryResponse, omitting private/sensitive data.\n","example":{"totalCount":3,"keys":[{"kid":"rsa_1751234383207","kty":"RSA","alg":"RSA-2048","status":"active","createdAt":"2025-06-29T21:59:45.020688416Z","expiresAt":"2027-06-29T21:59:45.020730344Z","softLimitExpiration":"2027-04-29T21:59:45.020730344Z","usageCount":0,"softUsageLimit":800000,"maxUsageLimit":1000000,"exportable":true},{"kid":"ml-kem_1751234478452","kty":"ML-KEM","alg":"ML-KEM-512","status":"active","createdAt":"2025-06-29T22:01:20.158879636Z","expiresAt":"2027-06-29T22:01:20.158905124Z","softLimitExpiration":"2027-04-29T22:01:20.158905124Z","usageCount":0,"softUsageLimit":800000,"maxUsageLimit":1000000,"exportable":true},{"kid":"rsa_1751234483381","kty":"RSA","alg":"RSA-2048","status":"active","createdAt":"2025-06-29T22:01:24.945698375Z","expiresAt":"2027-06-29T22:01:24.945717080Z","softLimitExpiration":"2027-04-29T22:01:24.945717080Z","usageCount":0,"softUsageLimit":800000,"maxUsageLimit":1000000,"exportable":true}]},"properties":{"totalCount":{"type":"integer","format":"int32","description":"Total count of keys in the response.","example":3},"keys":{"type":"array","description":"List of keys, each described by a KeyExportResponse model.","items":{"$ref":"#/components/schemas/KeySummaryResponse"}}}}},"securitySchemes":{"bearerAuth":{"type":"http","description":"Supply a valid Bearer JWT issued by the Auth API.","name":"bearerAuth","scheme":"bearer","bearerFormat":"JWT"}}}}