KEM API

The KEM (Key Encapsulation Mechanism) API provides post-quantum encryption and decryption using the Kyber768 algorithm. Qpher uses a hybrid KEM-DEM scheme: Kyber768 encapsulates a shared secret, which is then used with HKDF-SHA256 and AES-256-GCM to encrypt your data.

🔒Private keys never leave Qpher

All decryption operations happen inside the Qpher secure enclave. Your private keys are never exposed or exported.

---

Encrypt

POST/api/v1/kem/encryptEncrypt plaintext using Kyber768 KEM-DEM hybrid encryption.

Encrypts the provided plaintext using the KEM-DEM scheme with the specified key version. The key must be in active status.

Request body

Field	Type	Required	Description
plaintext	string (base64)	Yes	Base64-encoded data to encrypt. Maximum size: 1 MB.
key_version	integer	Yes	The version of the Kyber768 key to use. Must reference an active key.
mode	string	No	Encryption mode: "standard" (default) or "deterministic".
salt	string (base64)	Conditional	Base64-encoded salt. Required when mode is "deterministic".

⚠️Deterministic mode

Deterministic encryption (mode: "deterministic") produces identical ciphertext for the same plaintext and salt. Use it only when you need equality checks on encrypted data. Standard mode is recommended for all other use cases.

Response (200 OK)

Field	Type	Description
data.ciphertext	string (base64)	The encrypted data, base64-encoded.
data.key_version	integer	The key version used for encryption.
data.algorithm	string	Always "Kyber768".

Example

RequestPOST/api/v1/kem/encrypt

X-API-Key: qph_your_key_here
Content-Type: application/json

{
  "plaintext": "SGVsbG8sIFdvcmxkIQ==",
  "key_version": 1
}

Response200

{
  "data": {
    "ciphertext": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU2Nzg5...",
    "key_version": 1,
    "algorithm": "Kyber768"
  },
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Encrypt example

curl -X POST https://api.qpher.ai/api/v1/kem/encrypt \
  -H "X-API-Key: qph_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "plaintext": "SGVsbG8sIFdvcmxkIQ==",
    "key_version": 1
  }'

Errors

HTTP Status	Error Code	Description
400	ERR_KEM_001	Invalid encryption request — missing plaintext, invalid key_version, or bad encoding.
401	ERR_AUTH_001	Missing or invalid API key.
404	ERR_NOT_FOUND_001	Key version not found or key is not in active status.

---

Decrypt

POST/api/v1/kem/decryptDecrypt ciphertext using Kyber768 KEM-DEM hybrid decryption.

Decrypts ciphertext that was previously encrypted with the KEM encrypt endpoint. The referenced key must be in active or retired status.

Request body

Field	Type	Required	Description
ciphertext	string (base64)	Yes	Base64-encoded ciphertext returned by the encrypt endpoint.
key_version	integer	Yes	The key version that was used to encrypt this data.

Response (200 OK)

Field	Type	Description
data.plaintext	string (base64)	The decrypted data, base64-encoded.
data.key_version	integer	The key version used for decryption.
data.algorithm	string	Always "Kyber768".

Example

RequestPOST/api/v1/kem/decrypt

X-API-Key: qph_your_key_here
Content-Type: application/json

{
  "ciphertext": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU2Nzg5...",
  "key_version": 1
}

Response200

{
  "data": {
    "plaintext": "SGVsbG8sIFdvcmxkIQ==",
    "key_version": 1,
    "algorithm": "Kyber768"
  },
  "request_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "timestamp": "2026-01-15T10:30:01.000Z"
}

Decrypt example

curl -X POST https://api.qpher.ai/api/v1/kem/decrypt \
  -H "X-API-Key: qph_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "ciphertext": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXowMTIzNDU2Nzg5...",
    "key_version": 1
  }'

Errors

HTTP Status	Error Code	Description
400	ERR_KEM_002	Invalid decryption request — corrupt ciphertext or wrong key_version.
401	ERR_AUTH_001	Missing or invalid API key.
404	ERR_NOT_FOUND_001	Key version not found or key is in archived status.

---

Key Version Requirements

The key_version field is mandatory on all KEM operations. There is no implicit "use latest key" behavior.

Operation	Allowed Key Statuses
Encrypt	active only
Decrypt	active or retired

Use the Key Management API to list your keys and find the current active version.