Documentation
Comprehensive documentation and guides for using Shared Vault.
Technical Guides
Comprehensive technical documentation for tech-savvy security enthusiasts. Understand the architecture, design decisions, and cryptographic implementation details.
Quick Navigation
Architecture & Design Decisions
Shared Vault is a cloud-native SaaS platform for securely sharing secrets with other users. The system consists of a hardened Go backend exposing REST APIs consumed by a Vue 3/Nuxt 3 single-page application.
Cryptographic Primitives
The platform uses a hybrid approach combining classical and post-quantum cryptography for maximum security and future-proofing.
AEAD Cipher: AES-256-GCM
- Standard: NIST FIPS 197 (AES), NIST SP 800-38D (GCM mode)
- Key Length: 256 bits (32 bytes)
- Nonce: 96 bits (12 bytes) random per operation
- Rationale: Hardware-accelerated on modern CPUs, universally supported, provides both confidentiality and authentication
Hybrid Key Encapsulation Mechanism (KEM)
We use a hybrid KEM combining classical and post-quantum algorithms:
- Classical Component: X25519
- ECDH over Curve25519
- 32 bytes (256 bits) key size
- ~128 bits classical security
- Reference: RFC 7748
- Post-Quantum Component: ML-KEM-768
- Module-Lattice-Based KEM (formerly CRYSTALS-Kyber)
- NIST Level 3, ~192 bits quantum security
- Public Key: 1184 bytes, Secret Key: 2400 bytes
- Reference: NIST FIPS 203 (published August 14, 2024)
- Key Derivation: HKDF-SHA256
- Combines outputs from both KEMs
- Reference: RFC 5869
Hybrid Rationale: This approach ensures security as long as at least one algorithm (X25519 or ML-KEM) remains unbroken. It protects against unforeseen weaknesses in newer post-quantum algorithms while providing resilience against future quantum threats.
Email + TOTP Authentication
We chose email OTP + TOTP instead of passkeys for several reasons:
- Accessibility: Works on all devices (old and new), not tied to specific platforms
- No Biometric Requirements: Doesn't require biometric-capable devices
- Email as Foundation: "If your email isn't secured, no secret can be secured" - email security is fundamental
- Platform Independence: Not locked into specific platform ecosystems
Self-Managed KMS
The platform uses its own internal KMS rather than external cloud providers (AWS KMS, Google Cloud KMS, Azure Key Vault) to ensure:
- Complete control over key lifecycle
- No dependency on external services
- Cost efficiency (no per-operation charges)
- Privacy (keys never leave deployment environment)
Technical Glossary
AES-256-GCM
Advanced Encryption Standard with 256-bit keys in Galois/Counter Mode. Provides authenticated encryption with associated data (AEAD). Used for encrypting secret payloads and platform keys. Standard: NIST FIPS 197, NIST SP 800-38D.
X25519
Elliptic Curve Diffie-Hellman function over Curve25519. Classical component of our hybrid KEM for key wrapping. Provides ~128 bits of classical security. Standard: RFC 7748.
ML-KEM-768
Module-Lattice-Based Key-Encapsulation Mechanism (formerly CRYSTALS-Kyber) at security level 3. Post-quantum component of our hybrid KEM. Provides ~192 bits of quantum security. Standard: NIST FIPS 203 (published August 14, 2024).
XChaCha20-Poly1305
Extended ChaCha20 stream cipher with Poly1305 authentication. Used for end-to-end encryption of API payloads via the temporary token protocol. Provides 256-bit security. Standard: RFC 8439.
HKDF-SHA256
HMAC-based Key Derivation Function using SHA-256. Used to combine outputs from classical and post-quantum KEMs into a single wrapping key. Standard: RFC 5869.
DEK (Data Encryption Key)
Unique 256-bit symmetric key per secret. Encrypts the actual secret payload using AES-256-GCM. Each secret has its own DEK for cryptographic isolation.
KEK (Key Encryption Key)
Keys used to encrypt/wrap DEKs. Includes user KEK (hybrid KEM) and platform KEK (daily-rotating symmetric key). DEKs are wrapped with both user and platform KEKs for defense-in-depth.
Hybrid KEM
Combination of classical (X25519) and post-quantum (ML-KEM-768) key encapsulation mechanisms. Shared secrets from both are combined using HKDF-SHA256. Ensures security as long as at least one algorithm remains unbroken.
Temporary Token Protocol
End-to-end encryption protocol for API payloads. Client encrypts secrets using XChaCha20-Poly1305 with a temporary token secret before sending to server. Server never sees plaintext secrets. Token TTL: 1 hour.
TLS 1.3
Transport Layer Security version 1.3. Used for all network communications. Supports AES-256-GCM and ChaCha20-Poly1305 cipher suites. Standard: RFC 8446.
Multiple Layers of Defense-in-Depth
The platform implements a defense-in-depth encryption model with multiple layers:
Layer 1: Data Encryption Key (DEK)
Algorithm: AES-256-GCM
Purpose: Encrypt secret payloads
Key Size: 256 bits (unique per secret)
Description: Each secret is encrypted with its own unique key for cryptographic isolation
Layer 2: Your Personal Encryption Key
Algorithm: Hybrid KEM (X25519 + ML-KEM-768)
Purpose: Protect DEK with user's personal encryption key
Key Derivation: HKDF-SHA256 combining both KEM outputs
Description: Your personal encryption key protects all your secrets with future-proof, quantum-resistant algorithms
Layer 3: Platform-Wide Protection
Algorithm: AES-256-GCM
Purpose: Second layer of DEK protection
Rotation: Daily at UTC 00:00:00
Description: Daily-rotating platform key adds an extra layer of protection that changes every day
Layer 4: End-to-End Encryption
Algorithm: XChaCha20-Poly1305
Purpose: End-to-end encryption for API payloads
TTL: 1 hour
Description: All API communications are encrypted end-to-end, keeping secrets protected in transit
Security Properties
- Confidentiality: All secrets encrypted with 256-bit keys
- Integrity: AEAD modes detect tampering
- Authentication: Cryptographic proof of origin
- Forward Secrecy: Daily key rotation limits compromise impact
- Post-Quantum Resistance: Hybrid KEM protects against quantum attacks
- Zero Trust: Platform operators cannot access plaintext secrets
For more detailed documentation, see the full documentation repository.
Back to Home