Encryption Keys
1. What is it?
Encryption Keys are the cryptographic keys used for all encrypt/decrypt, sign/verify, and wrap/unwrap operations in QuantumAPI. They support NIST post-quantum cryptography standards (ML-KEM, ML-DSA, SLH-DSA) alongside classical algorithms (AES-256-GCM). Keys are stored encrypted at rest using envelope encryption and QRNG-generated nonces.
2. What is it for?
Data encryption at rest and in transit
Use ML-KEM or AES-256-GCM keys to encrypt secrets, files, and application data before storage.
Digital signatures
Use ML-DSA or SLH-DSA keys to sign documents, JWT tokens, and API payloads for authenticity and non-repudiation.
Key wrapping / hierarchy
Wrap DEKs (Data Encryption Keys) with a KEK (Key Encryption Key) to implement envelope encryption and key hierarchies.
BYOK
Import your own keys to retain control of key material while benefiting from QuantumAPI's management and audit capabilities.
3. Key concepts
| Term | Definition |
|---|---|
| Algorithm | The cryptographic algorithm the key is associated with (ML-KEM-768, ML-DSA-65, AES-256-GCM, etc.). |
| Key type | Encryption (KEM) keys for confidentiality vs. Signing keys (DSA) for authenticity. |
| Key state | Active: usable for all operations. Deprecated: decryption/verify only. Pending deletion: scheduled for destruction after grace period. |
| Default key | The key automatically selected for new encrypt/sign operations when no keyId is specified. |
| Rotation | Generating a new key version. The old version is deprecated (kept for decryption) while the new version becomes active. |
| Purge protection | Prevents immediate deletion. When enabled, a deleted key enters a grace period before final destruction. |
| BYOK | Bring Your Own Key — import external key material into QuantumAPI's key store. |
| JWK / JWKS | JSON Web Key / JSON Web Key Set. Standard format for exporting public keys for interoperability. |
| Grace period | The number of days between scheduling a key for deletion and its permanent destruction. |
4. How to use it
Creating a key
Open Encryption Keys
Choose the algorithm
Set as default (optional)
Enable purge protection (optional)
Save the key
Rotating a key
Open the key detail page and click Rotate. A new key version is created and becomes Active. The previous version moves to Deprecated status and remains available for decryption-only operations.
Scheduling deletion
Click Delete on the key detail page. If purge protection is enabled, the key enters Pending Deletion state for the configured grace period. During this time it cannot be used for new operations but can be restored.
Importing a key (BYOK)
Click Import Key, choose the format (PEM, JWK, or raw bytes), and paste or upload the key material. QuantumAPI wraps the imported key using the tenant KEK before storage.
Exporting the public key
For asymmetric keys, click Export Public Key. Supported formats: PEM, DER, JWK. Use the JWKS endpoint for public key distribution to external services.
GET /api/v1/keys/{id}/public?format=JWK
Authorization: Bearer <token>5. Field reference
| Field | Type | Required | Description |
|---|---|---|---|
| Name | string | Yes | Human-readable identifier. Unique within the tenant. |
| Algorithm | enum | Yes | ML-KEM-512 | ML-KEM-768 | ML-KEM-1024 | ML-DSA-44 | ML-DSA-65 | ML-DSA-87 | SLH-DSA-128s | AES-256-GCM |
| Default | boolean | No | If true, selected automatically when no keyId is provided. |
| State | Active | Deprecated | PendingDeletion | Read-only | Current lifecycle state of the key. |
| Purge protection | boolean | No | Requires grace period before final deletion. |
| Grace period (days) | integer | No | Days between deletion scheduling and destruction (1–90). |
| Scheduled deletion | ISO 8601 datetime | Read-only | When the key will be permanently destroyed. |
| Created at | ISO 8601 datetime | Read-only | Key creation timestamp. |
| Rotated at | ISO 8601 datetime | Read-only | Last rotation timestamp. |
6. Relationships
Encrypt / Decrypt
Encryption Keys are referenced by keyId in all encrypt, decrypt, sign, and verify operations.
Transit Engine
Transit Engine uses named encryption keys internally. The same keys can be used in both direct and transit modes.
QuantumVault — Secrets
Every vault secret is encrypted at rest with the tenant's default encryption key.
API Keys
API Keys with keys:manage scope can create, rotate, and delete encryption keys.
7. FAQ
What is the difference between ML-KEM and ML-DSA?
ML-KEM (Key Encapsulation Mechanism) is used to establish shared secrets for encryption. ML-DSA (Digital Signature Algorithm) is used to sign and verify messages. Choose ML-KEM for encrypting data and ML-DSA for signing.
Can I use a quantum-safe key for signing?
Yes. ML-DSA-44, ML-DSA-65, ML-DSA-87, and SLH-DSA-128s are all quantum-safe signature algorithms. ML-DSA-65 is the default choice for most use cases.
How does key rotation affect existing encrypted data?
Existing ciphertext remains valid — the deprecated key version is retained and used for decryption. Only new encrypt operations use the new key version. Re-encrypting existing data with the new key is done via the Transit Engine's re-wrap operation.
What happens to a key in pending-deletion state?
The key cannot be used for any new cryptographic operations. It can be restored (cancelling the deletion) during the grace period. Once the grace period expires, the key is permanently destroyed and all data encrypted with it becomes unrecoverable.
8. API / CLI reference
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/keys | List all encryption keys. |
| POST | /api/v1/keys | Create a new encryption key. |
| GET | /api/v1/keys/{id} | Get key details. |
| PUT | /api/v1/keys/{id} | Update key name or default flag. |
| POST | /api/v1/keys/{id}/rotate | Rotate the key (create new version). |
| DELETE | /api/v1/keys/{id} | Schedule key deletion. |
| GET | /api/v1/keys/{id}/public | Export the public key (PEM, DER, JWK, RAW). |
qapi keys list
qapi keys create --name my-key --algorithm ML-KEM-768
qapi keys rotate <key-id>
qapi keys export-public <key-id> --format JWK