rust-keyvault

A secure, production-grade cryptographic key management library for Rust.

Features

• Secure Key Storage - Encrypted at-rest with Argon2id + XChaCha20-Poly1305
• Key Rotation - Seamless key lifecycle management with versioning
• Persistent Storage - File-based backend with optional encryption
• Import/Export - Secure key exchange between vaults (new in v0.2.0!)
• Backup/Restore - Encrypted vault backups with compression (new in v0.2.0!)
• Audit Logging - Comprehensive security event tracking
• High Performance - ~2.4µs key generation, efficient storage
• Memory Safety - Automatic secret zeroization, constant-time operations
• Thread-Safe - Concurrent access with RwLock protection
• Benchmarked - Performance baselines established with Criterion

Security

• Zero Unsafe Code: #![forbid(unsafe_code)] - completely memory safe
• Security Audit: Passed (October 2025) - see SECURITY.md
• OWASP Compliant: Argon2id parameters meet OWASP 2024 guidelines
• Constant-Time Operations: Timing-attack resistant comparisons
• Automatic Zeroization: Secrets cleared from memory on drop

Supported Algorithms

*Asymmetric algorithms partially implemented - full support in v0.3.0

Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
rust-keyvault = "0.2.0"

Basic Usage

use rust_keyvault::*;
use rust_keyvault::key::{SecretKey, VersionedKey};
use rust_keyvault::storage::*;
use std::time::SystemTime;

// Create an encrypted file store
let config = StorageConfig { encrypted: true, ..Default::default() };
let mut store = FileStore::new("./keys", config)?;
store.init_with_password(b"your-secure-password")?;

// Generate a new key
let base_id = KeyId::generate_base()?;
let secret_key = SecretKey::generate(Algorithm::ChaCha20Poly1305)?;

let metadata = KeyMetadata {
    id: base_id.clone(),
    base_id: base_id.clone(),
    algorithm: Algorithm::ChaCha20Poly1305,
    created_at: SystemTime::now(),
    expires_at: None,
    state: KeyState::Active,
    version: 1,
};

let versioned_key = VersionedKey { key: secret_key, metadata };

// Store the key
store.store(versioned_key)?;

// Retrieve and use
let retrieved = store.retrieve(&base_id)?;
println!("Key algorithm: {:?}", retrieved.key.algorithm());

Key Rotation

// Rotate to a new version
let rotated_key = store.rotate_key(&base_id)?;
println!("New version: {}", rotated_key.metadata.version); // 2

// Get all versions
let versions = store.get_key_versions(&base_id)?;
println!("Total versions: {}", versions.len()); // 2

// Get latest active key
let latest = store.get_latest_key(&base_id)?;

Import/Export (v0.2.0)

use rust_keyvault::export::ExportedKey;
use rust_keyvault::storage::FileStore;

// Export key with password protection
let exported = store.export_key(&base_id, b"export-password")?;

// Serialize to JSON for transmission/storage
let json_export = exported.to_json()?;
std::fs::write("exported_key.json", &json_export)?;

// Import into another vault
let mut target_store = FileStore::new("./target", config)?;

// Deserialize from JSON
let json_str = std::fs::read_to_string("exported_key.json")?;
let exported_key = ExportedKey::from_json(&json_str)?;

// Import the key
let imported_id = target_store.import_key(&exported_key, b"export-password")?;
println!("Imported key with ID: {}", imported_id);

Backup/Restore (v0.2.0)

use rust_keyvault::backup::{BackupConfig, VaultBackup};

// Configure backup options
let backup_config = BackupConfig {
    include_audit_logs: true,
    compress: true,
    encryption_password: b"backup-password".to_vec(),
    comment: Some("Production backup".to_string()),
};

// Create encrypted backup
let backup = store.backup(b"backup-password", backup_config)?;

// Serialize to JSON and save
let backup_json = backup.to_json()?;
std::fs::write("vault.backup.json", &backup_json)?;

// Restore from backup
let backup_str = std::fs::read_to_string("vault.backup.json")?;
let backup = VaultBackup::from_json(&backup_str)?;

let mut restored_store = FileStore::new("./restored", config)?;
let restored_count = restored_store.restore(&backup, b"backup-password")?;
println!("Restored {} keys", restored_count);

Performance

Benchmarks run on AMD Ryzen 9 5950X (3.4 GHz base):

Full benchmark suite: cargo bench

Architecture

┌─────────────────┐
│  Applications   │
└─────────────────┘
         │
┌─────────────────────────────────────────┐
│     Core Key Management Layer           │
│  ┌─────────────┐    ┌────────────────┐  │
│  │  KeyStore   │    │ EncryptedStore │  │
│  │   Traits    │    │    Traits      │  │
│  └─────────────┘    └────────────────┘  │
│  ┌─────────────┐    ┌────────────────┐  │
│  │ MemoryStore │    │   FileStore    │  │
│  │  (Testing)  │    │  (Production)  │  │
│  └─────────────┘    └────────────────┘  │
└─────────────────────────────────────────┘
         │
┌─────────────────────────────────────────┐
│    Import/Export & Backup Layer         │
│  ┌─────────────┐    ┌────────────────┐  │
│  │ Key Export  │    │ Vault Backup   │  │
│  │ (Encrypted) │    │ (Compressed)   │  │
│  └─────────────┘    └────────────────┘  │
└─────────────────────────────────────────┘
         │
┌─────────────────────────────────────────┐
│      Cryptographic Primitives           │
│  ┌─────────────┐    ┌────────────────┐  │
│  │ AEAD Crypto │    │   Argon2 KDF   │  │
│  │ ChaCha/AES  │    │  Derivation    │  │
│  └─────────────┘    └────────────────┘  │
│  ┌─────────────┐    ┌────────────────┐  │
│  │  HKDF/HMAC  │    │  Zeroization   │  │
│  │ Derivation  │    │  Memory Safe   │  │
│  └─────────────┘    └────────────────┘  │
└─────────────────────────────────────────┘

Security Features

• Modern Cryptography: ChaCha20-Poly1305, XChaCha20-Poly1305, AES-256-GCM AEAD
• Memory Safety: Automatic secret zeroization with zeroize crate
• Key Derivation: Argon2id (64 MiB memory, t=4) password-based KDF
• HKDF: HMAC-SHA256 based key derivation for domain separation
• Authenticated Encryption: Built-in integrity protection with HMAC-SHA256
• Constant-Time Operations: Timing-attack resistant key comparisons
• Secure Random: ChaCha20-based CSPRNG for all random generation

Documentation

• API Documentation
• Usage Examples
• Security Policy - Threat model, security guarantees, best practices
• Changelog - Version history and release notes

Testing

Run the test suite:

# All tests
cargo test --all-features

# Integration tests
cargo test --test '*'

# Benchmarks
cargo bench

Contributing

Contributions are welcome! Please read our security policy in SECURITY.md before submitting changes.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.