Decrypt Data with KEM

This guide shows you how to decrypt ciphertext that was encrypted with Qpher Kyber768 hybrid KEM-DEM encryption, including how to handle retired key versions.

Prerequisites

• A Qpher account with an active API key
• Ciphertext previously produced by the Encrypt Data endpoint
• The key_version that was used during encryption

⚠️Key Version Must Match

You must provide the exact key_version that was used to encrypt the data. Qpher does not support implicit "latest" key resolution. If you do not know the key version, check the key_version field returned in the original encrypt response.

Step 1: Retrieve the Ciphertext and Key Version

When you encrypted data, the response included both the ciphertext and key_version. You need both values to decrypt:

{
  "data": {
    "ciphertext": "base64-encoded-ciphertext...",
    "key_version": 1,
    "algorithm": "Kyber768"
  }
}

Make sure you stored these values together. The key_version is essential for decryption.

Step 2: Send the Decrypt Request

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

Decrypt Data

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

Step 3: Understand the Response

RequestPOST/api/v1/kem/decrypt

Content-Type: application/json
x-api-key: qph_your_key_here

{
  "ciphertext": "base64-encoded-ciphertext...",
  "key_version": 1
}

Response200

{
  "data": {
    "plaintext": "SGVsbG8sIFdvcmxkIQ==",
    "key_version": 1,
    "algorithm": "Kyber768"
  },
  "request_id": "660e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-02-15T10:31:00Z"
}

Field	Description
plaintext	Base64-encoded decrypted plaintext — decode it to get the original data
key_version	The key version used for decryption (matches your request)
algorithm	The KEM algorithm used (Kyber768)
request_id	Unique request identifier for tracing and support

Decrypting with Retired Keys

After a key rotation, the old key version moves to retired status. You can still decrypt data that was encrypted with a retired key:

ℹ️Retired Keys Support Decryption

Retired keys can still be used for decryption and signature verification. This ensures you can always access data encrypted with older key versions. Only archived keys are completely disabled.

Key Status    | Encrypt | Decrypt
------------- | ------- | -------
active        |   Yes   |   Yes
retired       |   No    |   Yes
archived      |   No    |   No

If you need to re-encrypt data under a new key version, decrypt with the retired key and then encrypt with the current active key. See Key Versioning for a detailed re-encryption strategy.

Error Handling

HTTP Status	Error Code	Cause	Resolution
400	ERR_INVALID_001	Missing or invalid ciphertext or key_version	Ensure ciphertext is valid base64 and key_version is a positive integer
400	ERR_KEM_002	Ciphertext is malformed or corrupted	Verify the ciphertext was not truncated or modified
401	ERR_AUTH_001	Invalid or missing API key	Check your x-api-key header
404	ERR_KEM_003	Key version not found	Verify the key_version exists for your tenant
409	ERR_KEM_005	Key is archived — decryption not allowed	Contact support to restore the key to retired status
422	ERR_KEM_006	Decryption failed — wrong key or tampered ciphertext	Ensure you are using the correct key_version that was used to encrypt
429	ERR_RATE_001	Rate limit exceeded	Reduce request frequency or upgrade your plan

Related Guides

• Encrypt Data — Encrypt data using Kyber768 KEM
• Key Management — Generate and manage your KEM keys
• Key Versioning — Understand key lifecycle and re-encryption strategies
• Migration Guide — Migrate existing data to PQC encryption