Secure Operations (Non-Streaming)

Base64-payload APIs for data up to 5 MB**

---

1. Scope

The Secure tag exposes JSON-based endpoints for cryptographic tasks that fit comfortably in memory.
Each operation exchanges Base64-encoded payloads and returns a deterministic JSON envelope that contains:

Field	Purpose
\<operation-specific data>	The ciphertext, plaintext or signature bytes.
keyRequested	kid supplied by the client.
actualKeyUsed	kid ultimately processed  –  may differ after rotation or aliasing.
algorithmUsed	Canonical algorithm string, e.g. ML-KEM-768.
warnings[]	Lifecycle hints (expiry, usage, soft limits).
errorMessage	Populated only when the crypto operation fails.

All endpoints are protected by bearerAuth or rapidApiKey.

---

2. Operations

HTTP Verb	Path	Description	Request Body Schema	Success Status
POST	/api/crypto/encrypt	Encrypt plaintext with the public part of kid.	EncryptRequest	200
POST	/api/crypto/decrypt	Decrypt ciphertext with the private part of kid.	DecryptRequest	200
POST	/api/crypto/sign	Produce a digital signature using the private key.	SignRequest	200
POST	/api/crypto/verify	Validate a signature with the public key.	VerifySignatureRequest	200
POST	/api/crypto/reencrypt	Decrypt under oldKid and re-encrypt under newKid.	ReencryptRequest	200
POST	/api/crypto/resign	Verify using oldKid and re-sign using newKid.	ResignRequest	200

Size limits
Request and response bodies, including Base64 overhead, must not exceed 5 MB.
Exceeding the limit yields 413 Payload Too Large with an RFC 7807 problem envelope.

---

3. Schemas

3.1 EncryptRequest

Field	Type	Constraints
kid	string	Identifier of the public key.
data	string	Base64 plaintext.

3.2 EncryptResponse

Field	Type	Notes
encryptedData	string	Base64 ciphertext.
keyRequested	string	See § 1.
actualKeyUsed	string	See § 1.
algorithmUsed	string	See § 1.
warnings	string[]	See § 1.
errorMessage	string ∅	Present on error only.

3.3 DecryptRequest

Field	Type	Constraints
kid	string	Identifier of the private key.
encryptedData	string	Base64 ciphertext.

3.4 DecryptResponse

Field	Type	Notes
decryptedData	string	Base64 plaintext.
…standard metadata…		Same as EncryptResponse.

3.5 SignRequest

Field	Type
kid	string (private key)
data	string (Base64 payload)

3.6 SignResponse

Field	Type	Notes
signature	string	Base64 digital signature.
…standard metadata…		See § 1.

3.7 VerifySignatureRequest

Field	Type
kid	string (public key)
data	string (Base64 payload)
signature	string (Base64 signature)

3.8 VerifySignatureResponse

Field	Type	Notes
valid	boolean	true if the signature matches.
…standard metadata…		See § 1.

3.9 ReencryptRequest

Field	Type	Description
oldKid	string	Private key for decrypting the ciphertext.
newKid	string	Public key for re-encrypting the plaintext.
encryptedData	string	Base64 ciphertext.

3.10 ReencryptResponse

Field	Type
reencryptedData	string
…standard metadata…

3.11 ResignRequest

Field	Type
oldKid	string (public key)
newKid	string (private key)
data	string (Base64 payload)
oldSignature	string (Base64 signature)

3.12 ResignResponse

Field	Type
newSignature	string
…standard metadata…

---

4. Error Handling

All error responses follow RFC 7807 (application/problem+json).
Key conditions to expect:

HTTP Code	Reason
400	Malformed JSON, invalid Base64, incompatible algorithm.
401	Missing / invalid credentials.
404	kid not found or unsuitable for the requested operation.
409	Lifecycle conflict (revoked key, key type mismatch, etc.).
413	Request body larger than 5 MB after Base64 decoding.
500	Unexpected server error – retry or contact support.

---

5. Best Practices

1. Monitor warnings[] – rotate or patch keys proactively when soft limits arise.
2. Cache algorithmUsed – clients can shortcut discovery calls after the first invocation.
3. Use streaming endpoints for any payload that might exceed 5 MB after future growth.
4. Pair each encrypt with max-interval re-encrypt policies to maintain forward secrecy.

---

Document version 2.0 — compatible with OpenAPI definition 2025-05-09.
© 2025 AnkaTech Co. All rights reserved.