SecretumVault is a Rust-native secrets vault combining post-quantum cryptography (ML-KEM-768, ML-DSA-65) with classical crypto, multiple secrets engines, cedar-based policy authorization, and flexible storage backends.

Features

🔐 Post-Quantum Cryptography

ML-KEM-768: Key encapsulation mechanism for key exchange
ML-DSA-65: Digital signatures with post-quantum resistance
Hybrid mode: Classical + PQC algorithms for future-proof security
Multiple backends: OpenSSL, AWS-LC, RustCrypto (feature-gated)

🔑 Secrets Engines

KV Engine: Versioned key-value storage with encryption at rest
Transit Engine: Encryption/decryption without storing plaintext
PKI Engine: Certificate authority with X.509 support
Database Engine: Dynamic credentials for PostgreSQL, MySQL, others
Extensible: Add custom engines via trait implementation

🛡️ Authorization & Policies

Cedar Integration: Attribute-based access control (ABAC)
Fine-grained policies: Context-aware decisions (IP, time, environment)
Token management: Lease-based credentials with automatic revocation
Audit logging: Full request/response audit trail

💾 Flexible Storage

etcd: Distributed KV store with high availability
SurrealDB: Document database with queries
PostgreSQL: Proven relational database
Filesystem: Development/testing
Extensible: Implement StorageBackend trait for any backend

🚀 Cloud Native

Kubernetes-ready: Native K8s deployments with RBAC
Helm charts: Production-ready templated deployments
Docker: Multi-stage builds for minimal images
Prometheus metrics: Built-in observability
Structured logging: JSON or human-readable format

🔄 Enterprise Ready

TLS/mTLS: Encrypted client communication
Shamir Secret Sharing: Multi-factor unsealing (2-of-3, 3-of-5, etc.)
Auto-unseal: AWS KMS, GCP Cloud KMS, Azure Key Vault (planned)
High availability: Multi-node clustering (planned)
Replication: Active-passive disaster recovery (planned)

Quick Start

Local Development with Docker Compose

# Clone repository
git clone https://github.com/secretumvault/secretumvault.git
cd secretumvault

# Build and start
docker build -t secretumvault:latest -f deploy/docker/Dockerfile .
docker-compose -f deploy/docker/docker-compose.yml up -d

# Verify
curl http://localhost:8200/v1/sys/health

# View logs
docker-compose -f deploy/docker/docker-compose.yml logs -f vault

Kubernetes Deployment

# Deploy to cluster
kubectl apply -f deploy/k8s/01-namespace.yaml
kubectl apply -f deploy/k8s/02-configmap.yaml
kubectl apply -f deploy/k8s/03-deployment.yaml
kubectl apply -f deploy/k8s/04-service.yaml
kubectl apply -f deploy/k8s/05-etcd.yaml

# Port-forward and access
kubectl -n secretumvault port-forward svc/vault 8200:8200
curl http://localhost:8200/v1/sys/health

Helm Installation

# Install with default configuration
helm install vault deploy/helm/ \
  --namespace secretumvault \
  --create-namespace

# Customize backends and engines
helm install vault deploy/helm/ \
  --namespace secretumvault \
  --create-namespace \
  --set vault.config.storageBackend=postgresql \
  --set postgresql.enabled=true \
  --set vault.replicas=3

Core Concepts

Config-Driven Architecture

All components are selected via svault.toml configuration:

[vault]
crypto_backend = "openssl"  # or "aws-lc", "rustcrypto"

[storage]
backend = "etcd"  # or "surrealdb", "postgresql"

[seal]
seal_type = "shamir"
threshold = 2
shares = 3

[engines.kv]
path = "secret/"
versioned = true

[engines.transit]
path = "transit/"

No recompilation needed for backend changes—just update config.

Registry Pattern

Type-safe backend selection using registry pattern:

// CryptoRegistry dispatches config string to backend
let crypto = CryptoRegistry::create(&config.vault.crypto_backend)?;

// StorageRegistry creates backend from config
let storage = StorageRegistry::create(&config.storage)?;

// EngineRegistry mounts engines from [engines] section
let engines = EngineRegistry::mount_engines(&config.engines)?;

Async/Await

Built on Tokio for high concurrency:

Non-blocking I/O for all storage operations
Efficient resource utilization
Scales to thousands of concurrent connections

Token-Based Authentication

All API requests require X-Vault-Token header:

curl -H "X-Vault-Token: $VAULT_TOKEN" \
  http://localhost:8200/v1/secret/data/myapp

Tokens have:

TTL (time-to-live) with automatic expiration
Renewable for extended access
Revocable for immediate invalidation
Audit-logged for compliance

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     API Layer (Axum)                        │
│  /v1/secret/* | /v1/transit/* | /v1/pki/* | /v1/database/*  │
└──────────────────────────┬──────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
    ┌────────┐         ┌────────┐       ┌──────────┐
    │  Auth  │         │ Cedar  │       │  Metrics │
    │Manager │         │ Policy │       │Collection│
    └────────┘         │ Engine │       └──────────┘
                       └────────┘
                          │
    ┌─────────────────────┼──────────────────────┐
    │                     │                      │
    ▼                     ▼                      ▼
┌──────────┐    ┌──────────────────┐   ┌───────────────┐
│ KV Engine│    │ Transit Engine   │   │   PKI Engine  │
│  (Crypto)│    │  (Encrypt/Desc)  │   │ (Certificates)│
└──────────┘    └──────────────────┘   └───────────────┘
    │                     │                      │
    │                     ▼                      │
    │         ┌───────────────────────┐          │
    │         │  Database Engine      │          │
    │         │  (Dynamic Secrets)    │          │
    │         └───────────────────────┘          │
    │                     │                      │
    └─────────────────────┼──────────────────────┘
                          │
        ┌─────────────────┼────────────────┐
        │                 │                │
        ▼                 ▼                ▼
    ┌──────────┐    ┌──────────┐     ┌───────────┐
    │  Crypto  │    │ Storage  │     │   Seal    │
    │ Registry │    │ Registry │     │  Manager  │
    └──────────┘    └──────────┘     └───────────┘
        │                │                │
        │        ┌───────┼────────┐       │
        │        │       │        │       │
        ▼        ▼       ▼        ▼       ▼
    ┌────────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌────────────┐
    │OpenSSL │ │etcd │ │ DB  │ │ FS  │ │ Shamir SSS │
    └────────┘ └─────┘ └─────┘ └─────┘ └────────────┘
                          │
                          ▼
                 ┌─────────────────┐
                 │                 │
                 ▼                 ▼
            ┌─────────┐        ┌────────┐
            │SurrealDB│        │Postgres│
            └─────────┘        └────────┘

For detailed architecture: docs/ARCHITECTURE.md

Configuration

Minimal Setup

[vault]
crypto_backend = "openssl"

[server]
address = "0.0.0.0"
port = 8200

[storage]
backend = "etcd"

[storage.etcd]
endpoints = ["http://localhost:2379"]

[seal]
seal_type = "shamir"
threshold = 2
shares = 3

[engines.kv]
path = "secret/"
versioned = true

Production Setup

[vault]
crypto_backend = "aws-lc"  # Post-quantum support

[server]
address = "0.0.0.0"
port = 8200
tls_cert = "/etc/secretumvault/tls.crt"
tls_key = "/etc/secretumvault/tls.key"
tls_client_ca = "/etc/secretumvault/client-ca.crt"

[storage]
backend = "postgresql"

[storage.postgresql]
connection_string = "postgres://vault:${DB_PASSWORD}@db.example.com:5432/secretumvault"

[seal]
seal_type = "shamir"
threshold = 3
shares = 5

[engines.kv]
path = "secret/"
versioned = true

[engines.transit]
path = "transit/"

[engines.pki]
path = "pki/"

[engines.database]
path = "database/"

[logging]
level = "info"
format = "json"
output = "stdout"

[telemetry]
prometheus_port = 9090
enable_trace = true

[auth]
default_ttl = 24
cedar_policies_dir = "/etc/secretumvault/policies"

Full reference: docs/CONFIGURATION.md

API Examples

Initialize Vault

curl -X POST http://localhost:8200/v1/sys/init \
  -H "Content-Type: application/json" \
  -d '{
    "shares": 3,
    "threshold": 2
  }'

Response:

{
  "keys": ["key1", "key2", "key3"],
  "root_token": "root_token_abc123"
}

Store Secret (KV Engine)

curl -X POST http://localhost:8200/v1/secret/data/myapp \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "username": "admin",
      "password": "supersecret"
    }
  }'

Read Secret

curl http://localhost:8200/v1/secret/data/myapp \
  -H "X-Vault-Token: $VAULT_TOKEN"

Encrypt with Transit Engine

curl -X POST http://localhost:8200/v1/transit/encrypt/my-key \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA=="}'

Full API reference: docs/API.md

Deployment

Docker

docker build -t secretumvault:latest -f deploy/docker/Dockerfile .
docker run -p 8200:8200 \
  -v /etc/secretumvault:/etc/secretumvault:ro \
  secretumvault:latest

Docker Compose

docker-compose -f deploy/docker/docker-compose.yml up -d

Includes: vault, etcd, surrealdb, postgres, prometheus, grafana

Kubernetes

kubectl apply -f k8s/
# Or: helm install vault helm/

Complete Deployment Guide

See DEPLOYMENT.md for:

Docker build and run
Docker Compose multi-environment setup
Kubernetes manifests and scaling
Helm installation and customization
TLS/mTLS configuration
Prometheus monitoring
Troubleshooting

How-To Guides

Quick task guides for common operations:

Getting Started - Initial setup and first secrets
Initialize Vault - Create unseal keys and root token
Unseal Vault - Recover after restart
Manage Secrets - Create, read, update, delete
Configure Engines - Mount and customize engines
Setup Authorization - Cedar policies and tokens
Configure TLS - Enable encryption
Integrate with Kubernetes - Pod secret injection
Backup & Restore - Data protection
Monitor & Troubleshoot - Observability

Full guide: docs/HOWOTO.md

Project Structure

secretumvault/
├── src/
│   ├── main.rs                 # Server binary entry point
│   ├── config.rs               # TOML config parsing and validation
│   ├── error.rs                # Error types and conversions
│   ├── api/                    # HTTP API layer (Axum)
│   │   ├── server.rs           # Server setup and routing
│   │   ├── handlers/           # Endpoint handlers
│   │   └── middleware/         # Auth and Cedar middleware
│   ├── auth/                   # Authentication and authorization
│   │   ├── token.rs            # Token generation and validation
│   │   └── cedar.rs            # Cedar policy evaluation
│   ├── crypto/                 # Cryptographic backends
│   │   ├── backend.rs          # CryptoBackend trait and registry
│   │   ├── openssl.rs          # OpenSSL implementation
│   │   └── aws_lc.rs           # AWS-LC post-quantum backend
│   ├── storage/                # Storage backends
│   │   ├── mod.rs              # StorageBackend trait and registry
│   │   ├── filesystem.rs        # Filesystem implementation
│   │   ├── etcd.rs             # etcd implementation
│   │   ├── surrealdb.rs        # SurrealDB implementation
│   │   └── postgresql.rs        # PostgreSQL implementation
│   ├── engines/                # Secrets engines
│   │   ├── mod.rs              # Engine trait and registry
│   │   ├── kv.rs               # KV versioned store
│   │   ├── transit.rs          # Encryption as a service
│   │   ├── pki.rs              # Certificate authority
│   │   └── database.rs         # Dynamic database credentials
│   ├── core/                   # Core vault logic
│   │   ├── vault.rs            # VaultCore and initialization
│   │   ├── seal.rs             # Shamir SSS seal/unseal
│   │   └── router.rs           # Request routing to engines
│   ├── telemetry.rs            # Metrics, logging, audit
│   └── lib.rs                  # Library exports
├── deploy/                      # Deployment configurations
│   ├── docker/                 # Docker deployment
│   │   ├── Dockerfile          # Multi-stage container build
│   │   ├── docker-compose.yml  # Complete dev environment
│   │   └── config/             # Docker-specific config
│   ├── helm/                   # Helm charts for Kubernetes
│   └── k8s/                    # Raw Kubernetes manifests
│   ├── 01-namespace.yaml
│   ├── 02-configmap.yaml
│   ├── 03-deployment.yaml
│   ├── 04-service.yaml
│   ├── 05-etcd.yaml
│   ├── 06-surrealdb.yaml
│   └── 07-postgresql.yaml
├── helm/                       # Helm chart
│   ├── Chart.yaml
│   ├── values.yaml
│   └── templates/
├── docs/                       # Product documentation
│   ├── README.md               # Documentation index
│   ├── ARCHITECTURE.md         # System architecture
│   ├── CONFIGURATION.md        # Configuration reference
│   ├── API.md                  # API reference
│   ├── HOWOTO.md               # How-to guides
│   └── SECURITY.md             # Security guidelines
├── DEPLOYMENT.md               # Deployment guide
├── README.md                   # This file
└── Cargo.toml                  # Rust manifest

Development

Build

cargo build --all-features

Test

cargo test --all-features

Lint

cargo clippy -- -D warnings

Format

cargo fmt

Run

cargo run --all-features -- server --config svault.toml

Documentation

cargo doc --all-features --open

Feature Flags

Enable optional features via Cargo:

cargo build --features aws-lc,pqc,surrealdb-storage,etcd-storage,postgresql-storage

Available features:

aws-lc - AWS-LC cryptographic backend with post-quantum support
pqc - Post-quantum cryptography (ML-KEM-768, ML-DSA-65)
surrealdb-storage - SurrealDB storage backend
etcd-storage - etcd storage backend
postgresql-storage - PostgreSQL storage backend
server - Server binary
cli - Command-line tools
cedar - Cedar policy evaluation

Security

Design Principles

Encryption at rest: All secrets encrypted with master key
Least privilege: Cedar policies enforce fine-grained access
Audit logging: All operations logged and auditable
Secure defaults: Non-root execution, read-only filesystem, dropped capabilities
Post-quantum ready: Support for ML-KEM and ML-DSA

Security Guidelines

See docs/SECURITY.md for:

Key management best practices
Unsealing strategy
Token security
TLS/mTLS setup
Audit log review
Vulnerability reporting

Roadmap

Near-term (Next)

Additional secrets engines (SSH, Kubernetes Auth)
Auto-unseal mechanisms (AWS KMS, GCP Cloud KMS, Azure)
Secret rotation policies
Backup/restore utilities
Client SDKs (Go, Python, Node.js)

Medium-term

Active-passive replication
Multi-node clustering with Raft consensus
OAuth2/OIDC integration
Cloud IAM integration (AWS, GCP, Azure)
External Secrets Operator for K8s

Long-term

Active-active multi-region replication
Custom plugin system
FIPS 140-2 certification
HSM/TPM integration
Chaos engineering test suite

Contributing

Contributions welcome! Please:

Fork repository
Create feature branch: git checkout -b feature/name
Make changes following CLAUDE.md guidelines
Test: cargo test --all-features
Lint: cargo clippy -- -D warnings
Submit pull request

License

[License specification - add appropriate license]

Support

Documentation: Full guides in docs/
Issues: GitHub issue tracker
Security: Report vulnerabilities via security contact
Community: Discussions and Q&A

Acknowledgments

SecretumVault combines proven patterns from:

HashiCorp Vault (inspiration for API and engine design)
NIST PQC standardization (ML-KEM-768, ML-DSA-65)
AWS Cedar (policy language and authorization)
Kubernetes ecosystem (native cloud deployment)

Built with ❤️ in Rust for modern cryptographic secrets management

Languages

Rust 67.8%

HTML 21%

Just 9.1%

NCL 0.7%

Shell 0.7%

Other 0.7%