Secure Operations (Streaming)

1. Scope

Endpoints under the Secure Streaming tag process arbitrarily sized payloads by reading/writing streams instead of full Base64 blobs. Each call is a multipart/form-data request with two parts:

Part	Content-Type	Purpose
`metadata`	`application/json`	Operation parameters (kid, signature, etc.).
`file`	`application/octet-stream`	Raw binary payload (plaintext, ciphertext or document to sign).

2. Operations

HTTP Verb	Path	Primary Function	`metadata` Schema	Response Body	Success
POST	`/api/crypto/stream/encrypt`	Encrypt large plaintext	`EncryptStreamRequest`	Ciphertext stream	200
POST	`/api/crypto/stream/decrypt`	Decrypt large ciphertext	`DecryptStreamRequest`	Plaintext stream	200
POST	`/api/crypto/stream/sign`	Sign large data	`SignStreamRequest`	Signature stream	200
POST	`/api/crypto/stream/verify`	Verify signature against large data	`VerifySignatureStreamRequest`	JSON `VerifySignatureResponse`	200
POST	`/api/crypto/stream/reencrypt`	Decrypt under oldKid and encrypt under newKid	`ReencryptStreamRequest`	Ciphertext stream	200
POST	`/api/crypto/stream/resign`	Verify with oldKid and sign with newKid	`ResignStreamRequest`	Signature stream	200

3. Response Headers

3.1 Single-Key Operations

encrypt, decrypt, sign

Header	Meaning
X-Key-Requested	kid sent by the client.
X-Key-Used	Actual kid processed (may change after rotation).
X-Algorithm-Used	Canonical algorithm string, e.g. `AES-256-GCM`.
X-Key-Expiration-Warning	Present if `expiresAt` or `softLimitExpiration` is near.
X-Key-Usage-Limit-Warning	Present when `usageCount` approaches limits.

3.2 Dual-Key Operations

reencrypt, resign

Headers are emitted twice — OldKey prefix for the source key,
NewKey prefix for the destination key, e.g.:

X-OldKey-Used

X-OldKey-Algorithm-Used

X-OldKey-Expiration-Warning

X-OldKey-Usage-Limit-Warning

X-NewKey-Used

X-NewKey-Algorithm-Used

X-NewKey-Expiration-Warning

X-NewKey-Usage-Limit-Warning

### 3.3 Verify Operation/stream/verifyreturns JSON and therefore does **not** send stream headers. All lifecycle hints are embedded insidewarnings[]`.

4. Metadata Schemas

All objects are defined in the OpenAPI under #/components/schemas/*.

ID	Core Fields
`EncryptStreamRequest`	`kid` (public)
`DecryptStreamRequest`	`kid` (private)
`SignStreamRequest`	`kid` (private)
`VerifySignatureStreamRequest`	`kid`, `signatureBase64`
`ReencryptStreamRequest`	`oldKid` (private), `newKid` (public)
`ResignStreamRequest`	`oldKid` (public), `newKid` (private), `oldSignatureBase64`

Every field is a Unicode string; binary blobs are always Base64-encoded.

5. Sample `metadata` Part

{
  "kid": "myPublicKid"            // Encrypt / Decrypt / Sign
}`

`{
  "kid": "myVerifyKid",
  "signatureBase64": "QmFzZTY0U2lnbg=="   // Verify
}`

`{
  "oldKid": "rsaKey01",
  "newKid": "mlkemKey02",
  "oldSignatureBase64": "QmFzZTY0T2xkU2ln"  // Resign
}`

6. Error Handling

Errors are conveyed via RFC 7807 (application/problem+json):

HTTP Code	Typical Cause
400	Missing/invalid `metadata` JSON, bad Base64, wrong algorithm.
401	Absent or invalid bearer/API key.
404	`kid` not found, or key lacks required capability.
409	Key revoked, expired or algorithm mismatch.
500	Unexpected server fault -- include `instance` & `timestamp` when contacting support.

7. Best Practices

Stream efficiently -- pipe file descriptors directly to the HTTP client; avoid buffering.
Inspect headers -- rotate or patch keys once the first warnings appear.
Resume on failure -- chunked uploads simplify resumable-stream retry logic.
Pair with non-streaming -- for configuration probes or small control messages (< 10 kB).