API Guide: Quantum-Resistant Encryption System v0.1 (PoC)

1. Introduction

This document provides a guide to using the API for the Quantum-Resistant Encryption System. The API allows for encryption and decryption using various hybrid and advanced schemes, with keys and sensitive components managed via HashiCorp Vault.

Base URL: http://127.0.0.1:8000/api/v1 (for local development)

Authentication: All endpoints require an API key to be passed in the X-API-Key request header. For the PoC, the default key is poc_super_secret_api_key_123!. This can be overridden by setting the SERVER_API_KEY environment variable when starting the API server.

Data Format: All request and response bodies are in JSON. Binary data (plaintext, ciphertext, passwords, factors, QNE keys) must be Base64 encoded strings.

2. Common Error Responses

400 Bad Request: Invalid input format, missing required fields, or invalid Base64 encoding.
```
{ "detail": "Descriptive error message." }
```
401 Unauthorized: Missing or invalid X-API-Key header.
```
{ "detail": "Invalid API Key." }
```

404 Not Found: If a requested key_id_hex does not exist in Vault.

{ "detail": "Key ID '' not found in Vault. Nothing to delete." }

422 Unprocessable Content: The request was well-formed, but a cryptographic processing error occurred.
```
{ "detail": " processing error: " }
```
503 Service Unavailable: A required backend service (like the QNE Pool) is not available.
```
{ "detail": "QNE Pool not available for API." }
```

3. API Endpoints

3.1 Layered Encryption (Epic 1)

`POST /encrypt/layered`

Encrypts plaintext using the layered scheme (AES-CBC with KEM-encapsulated key). The KEM private key is stored in Vault.

Request Body:

{
    "plaintext_b64": "string (Base64 encoded plaintext)"
}

Success Response (200 OK):

{
    "ciphertext_b64": "string (Base64 encoded ciphertext, includes Vault key_id)"
}

`POST /decrypt/layered`

Decrypts ciphertext from the layered scheme. Retrieves KEM private key from Vault using the embedded key_id.

Request Body:

{
    "ciphertext_b64": "string (Base64 encoded ciphertext from /encrypt/layered)"
}

Success Response (200 OK):

{
    "plaintext_b64": "string (Base64 encoded original plaintext)"
}

3.2 Parallel Encryption - Random K1 (Epic 1)

`POST /encrypt/parallel/random`

Encrypts using the parallel scheme with a randomly generated K1. K1 and the KEM private key are stored in Vault.

`POST /decrypt/parallel/random`

Decrypts parallel scheme ciphertext (PoC uses the C1 path by retrieving K1 from Vault).

3.3 Parallel Encryption - KDF K1 (Epic 1 + Epic 3 Anchoring)

`POST /encrypt/parallel/kdf`

Encrypts using the parallel scheme where K1 is derived via an anchored KDF from a password and other factors.

`POST /decrypt/parallel/kdf`

Decrypts parallel scheme ciphertext (PoC uses the C1 path by re-deriving K1 with provided credentials and salts from Vault).

3.4 Layered Encryption with QNE Infusion (Epic 1 + Epic 2)

`POST /encrypt/layered_qne`

Wraps the output of Layered Encryption with the QNE infusion layer (AES-GCM with AAD).

`POST /decrypt/layered_qne`

Decrypts the QNE-infused ciphertext. Requires the QNE layer key (returned during encryption in the PoC).

3.5 Parallel KDF Encryption with QNE Infusion (Epic 1 + Epic 3 + Epic 2)

`POST /encrypt/parallel_kdf_qne`

Wraps the output of Parallel KDF Encryption with the QNE infusion layer.

`POST /decrypt/parallel_kdf_qne`

Decrypts the QNE-infused ciphertext. Requires credentials for KDF re-derivation and the QNE layer key.

3.6 Key Management (Vault)

`DELETE /vault/keys/{key_id_hex}`

Deletes a key set from Vault associated with an encryption operation, identified by its 32-character hex UUID.