Security Architecture
Qpher is built from the ground up as a security product. Every layer of the platform enforces strict boundaries around your cryptographic keys and data. This page explains the key architectural decisions that keep your keys safe.
Your private keys never leave our secure enclave. All cryptographic operations happen server-side, inside the KMS-Orchestrator boundary.
Service Diagramâ
Qpher uses a microservices architecture. Each service has a single responsibility, and communication between services is authenticated with service tokens.
The KMS-Orchestrator is the only service that can access private key material. The KEM Service and Signature Service send operation requests to the KMS-Orchestrator and receive results (ciphertexts, signatures) back. They never see the underlying keys.
Gateway Auth Pipelineâ
Every API request passes through a 7-stage authentication and authorization pipeline before reaching any backend service.
| Stage | What Happens | On Failure |
|---|---|---|
| 1. Skip check | Health and metrics endpoints bypass auth | -- |
| 2. Extract API key | Read the x-api-key header | 401 Missing API key |
| 3. Resolve tenant | Hash the key and look up the tenant | 401 Invalid API key |
| 4. Inject context | Attach X-Tenant-ID and X-Request-ID headers | -- |
| 5. Rate limit | Check per-tenant rate limits via Redis | 429 Rate limit exceeded |
| 6. Policy check | Evaluate access rules in the Policy Engine | 403 Access denied |
| 7. Route | Forward the request to the appropriate service | -- |
No request reaches a backend service without passing all seven stages.
Private Keys Stay in the KMS-Orchestratorâ
The most important security boundary in Qpher is the KMS-Orchestrator enclave:
- Private keys are generated inside the KMS-Orchestrator and never leave it.
- Keys are encrypted at rest using AES-256-GCM before being written to disk.
- The database stores a handle (a reference path), not the key bytes themselves.
- There is no API endpoint to export or download a private key.
When you call /kem/encrypt or /signature/sign, the KEM Service or Signature Service
forwards your request to the KMS-Orchestrator. The KMS-Orchestrator loads the private key,
performs the operation, and returns only the result.
Tenant Isolationâ
Qpher is a multi-tenant platform. Every tenant's data is strictly separated through four layers of isolation:
- Repository layer -- Every database query includes a
tenant_idfilter. There is no way to query data across tenants. - Database constraints -- Unique indexes are scoped to
(tenant_id, ...), preventing data collisions between tenants. - Context propagation -- The gateway injects
X-Tenant-IDinto every downstream request. Services never derive the tenant ID from user input. - Gateway enforcement -- The API key lookup determines the tenant. A tenant can only access resources associated with their own API key.
Even if a bug existed in a service, database constraints and repository-level filtering prevent one tenant from accessing another tenant's keys or data.
Fail-Closed Designâ
Qpher follows a fail-closed philosophy: when something goes wrong, the system denies access rather than allowing it.
| Scenario | Behavior |
|---|---|
| Policy Engine is unavailable | All requests are denied (503) |
| Tenant lookup fails | Request is rejected (401) |
| Rate limit service is down | Requests are denied, not allowed through |
| Missing configuration at startup | Service refuses to start |
| PQC cryptographic operation fails | Error is returned, never falls back to weaker crypto |
This approach means brief outages may temporarily block requests, but it guarantees that a failure condition never silently weakens your security posture.
Cryptographic Foundation â Open Quantum Safeâ
Qpher uses liboqs (Open Quantum Safe) as the underlying implementation of all post-quantum cryptographic algorithms. Qpher does not implement cryptographic primitives from scratch â we build on a peer-reviewed, widely adopted open-source library maintained by academic and industry cryptographers.
| Component | Role |
|---|---|
| liboqs (C library) | Core PQC algorithms: ML-KEM-768 (Kyber768) and ML-DSA-65 (Dilithium3) |
| liboqs-python | Python bindings used by the KMS-Orchestrator, KEM Service, and Signature Service |
| NIST compliance | liboqs implements FIPS 203 (ML-KEM) and FIPS 204 (ML-DSA) as standardized by NIST |
Rolling your own cryptography is one of the most common security anti-patterns. By building on the Open Quantum Safe project â which has been reviewed by NIST, adopted by major TLS libraries (including OpenSSL and BoringSSL via oqs-provider), and tested across hundreds of deployments â Qpher inherits years of hardening instead of starting from zero.
The liboqs version used in production is pinned and recorded in every Docker image build. The full list of open-source libraries Qpher depends on is published at qpher.ai/legal/open-source.
Hybrid PQC + Classical Cryptographyâ
Qpher supports two cryptographic modes, giving customers the choice based on their risk tolerance and compliance requirements.
Two Kinds of "Hybrid"â
The term "hybrid" appears in two different contexts in post-quantum cryptography. It is important to understand the distinction:
| Term | What It Means | Qpher Version |
|---|---|---|
| KEM-DEM hybrid | Kyber768 (KEM) + AES-256-GCM (DEM) â combining a PQC key exchange with a symmetric cipher for payload encryption | All plans |
| PQC + classical hybrid | Combining a PQC algorithm with a traditional algorithm (e.g., X25519 + Kyber768) so that security holds even if one algorithm is broken | Pro, Enterprise |
Qpher uses KEM-DEM hybrid internally for all encryption operations (see KEM-DEM Hybrid Encryption). This means every encryption operation combines Kyber768 with AES-256-GCM.
PQC + Classical Hybrid Modeâ
Hybrid PQC + classical algorithms provide defense-in-depth by combining a PQC algorithm
with a battle-tested classical algorithm. Add "algorithm": "X-Wing" or
"algorithm": "Composite-ML-DSA" to your API requests. Omitting the parameter defaults
to PQC-only mode.
Qpher offers hybrid mode that combines PQC algorithms with classical algorithms for defense-in-depth. This follows the approach adopted by AWS, Google Cloud, and Cloudflare in production:
| Operation | PQC-Only (default) | Hybrid (Pro/Enterprise) |
|---|---|---|
| KEM | ML-KEM-768 (Kyber768) | X-Wing: X25519 + ML-KEM-768 |
| Signatures | ML-DSA-65 (Dilithium3) | Composite-ML-DSA: ECDSA P-256 + ML-DSA-65 |
Why hybrid matters: PQC algorithms are rigorously standardized but relatively new. Classical algorithms like X25519 and ECDSA have decades of battle-testing. Hybrid mode ensures that even if a breakthrough in lattice cryptanalysis were discovered, the classical component would maintain security. Once PQC algorithms have accumulated more real-world deployment history, PQC-only mode will be the recommended long-term default.
For full technical details, see ADR-0031 (Hybrid PQC + Classical Cryptography) in the project repository.
What's Nextâ
- Non-Exportable Keys -- How private keys are protected
- Encryption at Rest -- AES-256-GCM key storage
- Zero Trust -- Per-request authorization
- Compliance -- Standards and certifications