A lightweight, security-focused Key Management Service (KMS) inspired by real-world HSM and cloud KMS workflows.
KeyVault Lite is conceptual API based on functionlity of a real Hardware Security Module. It demonstrate security engineering principles, cryptographic key lifecycle management, access control, and auditability.
KeyVault Lite is a backend service that securely manages cryptographic keys and performs cryptographic operations on behalf of other services - without ever exposing raw keys.
It is conceptually similar to:
- AWS KMS
- GCP Cloud KMS
- HashiCorp Vault (key-management subset)
This project demonstrates:
- Secure key lifecycle management (create, rotate, revoke)
- Envelope encryption
- Per-service identity and role-based access control
- Tamper-evident audit logging
- Security-first backend design decisions
This is not about crypto APIs.
It is about designing systems that protect secrets by default.
- Keys never leave the system
- All cryptographic operations are mediated
- Every sensitive action is authenticated, authorized, and audited
- Database storage is assumed compromised
- Audit logs must detect tampering
- Blast radius must be minimized
Key points:
- Clients never talk directly to storage
- Cryptographic logic is isolated
- Audit logging is a first-class component
- Clear trust boundaries are enforced
Flow summary:
- Client requests encryption
- Service identity is authenticated and authorized
- Active key version is fetched
- A Data Encryption Key (DEK) is generated per request
- Data is encrypted with the DEK
- DEK is encrypted with a Key Encryption Key (KEK)
- Operation is audit-logged
- Ciphertext is returned to the client
- Clients reference logical keys
- Each key has multiple versions
- Only one version is ACTIVE at a time
- Old versions can decrypt but never encrypt
This enables safe, zero-downtime key rotation.
KeyVault Lite never encrypts data directly with master keys.
MASTER KEY (environment variable)
↓ encrypts
KEY ENCRYPTION KEY (KEK)
↓ encrypts
DATA ENCRYPTION KEY (DEK)
↓ encrypts
USER DATA
Benefits:
- Safe key rotation
- Reduced blast radius
- Industry-standard KMS design
Clients are services, not users.
Each service:
- Has a stable identity
- Is assigned a role
- Has explicit permissions
- Is fully auditable
This mirrors real IAM-based systems.
Every sensitive operation is logged:
- Service identity
- Action
- Key ID and version
- Timestamp
- Result
Logs are:
- Append-only
- Hash-chained
- Tamper-evident
CREATE TABLE keys (
id TEXT PRIMARY KEY,
type TEXT NOT NULL,
purpose TEXT NOT NULL,
status TEXT NOT NULL,
created_at TIMESTAMP NOT NULL
);CREATE TABLE key_versions (
id TEXT PRIMARY KEY,
key_id TEXT NOT NULL,
version INTEGER NOT NULL,
encrypted_key BLOB NOT NULL,
status TEXT NOT NULL,
created_at TIMESTAMP NOT NULL
);CREATE TABLE services (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
role TEXT NOT NULL,
active BOOLEAN NOT NULL
);CREATE TABLE audit_logs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
service_id TEXT NOT NULL,
action TEXT NOT NULL,
key_id TEXT,
key_version INTEGER,
timestamp TIMESTAMP NOT NULL,
result TEXT NOT NULL,
prev_hash TEXT,
hash TEXT NOT NULL
);KeyVault Lite implements a conservative key revocation model.
Once a key is revoked:
- New encryption operations are blocked immediately
- Access to previously encrypted data may also be restricted depending on repository-level filtering
- This design favors security and simplicity over availability
A soft-revocation model (allowing decryption after revocation) is discussed as an alternative design in the threat model.
| Role | Permissions |
|---|---|
| ADMIN | key_create, key_rotate, key_revoke, encrypt, decrypt, audit_read |
| SERVICE | key_create, key_rotate, encrypt, decrypt, |
| AUDITOR | audit_read |
Authorization is enforced before every operation.
POST /keys
{
"type": "AES",
"size": 256,
"purpose": "ENCRYPT"
}POST /keys/{key_id}/encrypt
{
"plaintext": "hello world"
}Response:
{
"ciphertext": "BASE64...",
"encrypted_dek": "BASE64...",
"key_version": 3
}POST /keys/{key_id}/rotate
- Creates a new key version
- Deprecates the old version
- Preserves ability to decrypt old data
GET /audit
Accessible only to ADMIN and AUDITOR.
This project includes explicit security documentation:
- 📄 Threat Model:
threat_model.md - 🛡️ Security Policy:
SECURITY.md
These documents clearly define:
- Security assumptions
- Threats and mitigations
- Out-of-scope risks
- Responsible disclosure process
pip install -r requirements.txt
export KEYVAULT_MASTER_KEY=<base64-encoded-32-bytes>
uvicorn app.main:app --reload- Use curl or Postman
- Simulate services via headers
- Rotate keys and decrypt old data
- Verify audit log integrity
KeyVault Lite models how real KMS systems think internally:
- Keys are more sensitive than data
- Access must be explicit
- Rotation must be safe
- Auditability is non-negotiable
It demonstrates system-level security engineering, not just API development.
The following features are intentionally out of scope for the current implementation:
- Asymmetric signing and verification (RSA/ECDSA)
- Signature-only key purposes
- Public key export for verification
These extensions would follow the same key-versioning, RBAC, and audit principles demonstrated here.
MIT License This project is open-source and intended for educational and portfolio use only.
Do not use this system to manage real secrets. KeyVault Lite is an educational project, not a production security solution.