secretumvault/docs/README.md

SecretumVault Documentation

Complete documentation for SecretumVault secrets management system.

Documentation Index

Getting Started

• Architecture - System design, components, and data flow
• How-To Guide - Step-by-step instructions for common tasks
• Configuration - Complete configuration reference and options
• Features Control - Build features and Justfile recipes

Operations & Development

• Deployment Guide - Docker, Kubernetes, and Helm deployment
• API Reference - HTTP API endpoints and request/response formats
• Security Guidelines - Security best practices and hardening

Build & Features

• Build Features - Cargo features, compilation options, dependencies
• Post-Quantum Cryptography - PQC algorithms, backend support, configuration
• Development Guide - Building, testing, and contributing

---

Quick Navigation

I want to...

Deploy SecretumVault → Start with Deployment Guide

Understand the architecture → Read Architecture

Configure vault for my environment → See Configuration

Use the REST API → Check API Reference

Set up authentication and policies → Follow How-To: Setup Authorization

Integrate with Kubernetes → See How-To: Kubernetes Integration

Enable post-quantum cryptography → Read PQC Support Guide, Configuration: Crypto Backends, or Build Features: PQC

Rotate secrets automatically → Check How-To: Secret Rotation

Set up monitoring → See How-To: Monitoring

Contribute code → Read Development Guide

---

Documentation Structure

docs/
├── README.md                          # This file
├── index.md                           # mdBook introduction
├── user-guide/
│   ├── README.md
│   ├── configuration.md               # Configuration reference
│   └── howto.md                       # Step-by-step how-to guides
├── architecture/
│   ├── README.md
│   ├── overview.md                    # System architecture and design
│   └── complete-architecture.md       # Detailed architecture reference
├── operations/
│   ├── README.md
│   └── deployment.md                  # Deployment guide
└── development/
    ├── README.md
    ├── build-features.md             # Cargo features and build options
    ├── features-control.md           # Feature control and Justfile recipes
    └── pqc-support.md                # Post-quantum cryptography support
└── ../
    ├── README.md                      # Main overview
    └── Cargo.toml                     # Rust manifest with all dependencies

---

Key Concepts

Config-Driven Architecture

Everything in SecretumVault is configurable via svault.toml:

• Crypto backend: Choose between OpenSSL, AWS-LC, RustCrypto
• Storage backend: etcd, SurrealDB, PostgreSQL, or filesystem
• Secrets engines: Mount KV, Transit, PKI, Database dynamically
• Authorization: Cedar policies from configuration directory
• Seal mechanism: Shamir SSS with configurable thresholds

No recompilation needed—just update the TOML file.

Registry Pattern

Backend selection uses type-safe registry pattern:

Config String → Registry Dispatch → Concrete Backend
    "etcd"   → StorageRegistry  → etcdBackend
    "openssl" → CryptoRegistry  → OpenSSLBackend
    "kv"     → EngineRegistry   → KVEngine

Async/Await Foundation

All I/O is non-blocking using Tokio:

HTTP Request → Axum Router → Engine → Storage Backend (async/await)
                                     → Crypto Backend (async/await)
                                     → Policy Engine (sync)

Token-Based Authentication

Every API request requires a token:

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

Tokens include:

• TTL (auto-expiration)
• Renewable (extend access)
• Revocable (immediate invalidation)
• Audited (logged in detail)

---

Feature Overview

Cryptography

Feature	Status	Notes
OpenSSL backend (RSA, ECDSA)	✅ Complete	Stable, widely supported
AWS-LC backend (RSA, ECDSA)	✅ Complete	Post-quantum ready
ML-KEM-768 (Key encapsulation)	✅ Feature-gated	Post-quantum, feature: pqc
ML-DSA-65 (Digital signatures)	✅ Feature-gated	Post-quantum, feature: pqc
RustCrypto backend	🔄 Planned	Pure Rust PQC implementation
Hybrid mode (classical + PQC)	✅ Complete	Use both for future-proof security

Secrets Engines

Engine	Status	Features
KV (Key-Value)	✅ Complete	Versioned storage, encryption at rest
Transit (Encryption)	✅ Complete	Encrypt/decrypt without storage
PKI (Certificates)	✅ Complete	CA, certificate issuance, CRL
Database (Dynamic)	✅ Complete	PostgreSQL, MySQL, credential rotation
SSH (Future)	🔄 Planned	SSH certificate issuance
AWS (Future)	🔄 Planned	Dynamic AWS IAM credentials

Storage Backends

Backend	Status	Use Case
etcd	✅ Complete	Distributed HA (production)
SurrealDB	✅ Complete	Document queries (testing)
PostgreSQL	✅ Complete	Relational (production)
Filesystem	✅ Complete	Development/testing
S3 (Future)	🔄 Planned	Cloud object storage
Consul (Future)	🔄 Planned	Service mesh integration

Authorization

Feature	Status	Notes
Cedar policies	✅ Complete	AWS open-source ABAC language
Token management	✅ Complete	TTL, renewal, revocation
Audit logging	✅ Complete	Full request/response audit
IP-based policies	✅ Complete	Context-aware decisions
Time-based policies	✅ Complete	Schedule-based access

Deployment

Format	Status	Features
Docker	✅ Complete	Multi-stage build, minimal image
Docker Compose	✅ Complete	Full dev stack (6 services)
Kubernetes	✅ Complete	Manifests + RBAC + StatefulSet
Helm	✅ Complete	Production-ready chart
Terraform (Future)	🔄 Planned	Infrastructure as code

Observability

Feature	Status	Features
Prometheus metrics	✅ Complete	13+ metrics, text format
Structured logging	✅ Complete	JSON or human-readable
Audit logging	✅ Complete	Encrypted storage + display
Tracing (Future)	🔄 Planned	OpenTelemetry integration

---

Common Tasks

Build from Source

# Standard build (OpenSSL only)
cargo build --release

# With all features
cargo build --release --all-features

# With specific features
cargo build --release --features aws-lc,pqc,postgresql-storage

See Build Features for full feature list.

Run Locally

# Start with config file
cargo run --release -- server --config svault.toml

# Or with Docker Compose
docker-compose up -d

Deploy to Kubernetes

# Apply manifests
kubectl apply -f k8s/

# Or use Helm
helm install vault helm/ --namespace secretumvault --create-namespace

Configure Storage

Edit svault.toml:

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

[storage.postgresql]
connection_string = "postgres://user:pass@host:5432/vault"

Set Up TLS

# Generate certificate
openssl req -x509 -newkey rsa:4096 -out tls.crt -keyout tls.key

# Update config
[server]
tls_cert = "/etc/secretumvault/tls.crt"
tls_key = "/etc/secretumvault/tls.key"

---

Support & Troubleshooting

Check Health

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

View Logs

# Docker Compose
docker-compose logs -f vault

# Kubernetes
kubectl -n secretumvault logs -f deployment/vault

Common Issues

• Pod not starting: Check kubectl describe pod
• Storage connection error: Verify backend endpoint in ConfigMap
• TLS errors: Check certificate paths and permissions
• High memory: Increase resource limits in values.yaml

See How-To: Troubleshooting for detailed guidance.

---

Next Steps

1. New to SecretumVault? → Read Architecture
2. Want to deploy? → Follow Deployment Guide
3. Ready to use? → Start with How-To Guides
4. Need to configure? → Check Configuration Reference
5. Building a feature? → See Development Guide

---

Documentation Quality

All documentation is:

• ✅ Accurate: Reflects current implementation
• ✅ Complete: Covers all major features
• ✅ Practical: Includes real examples
• ✅ Actionable: Step-by-step procedures
• ✅ Searchable: Organized with clear structure

---

Last updated: 2025-12-21

For the latest updates, check the repository or create an issue on GitHub.