Hero Vault Key-Value Store Module

The Key-Value Store (KVS) module provides an encrypted key-value store for securely storing sensitive data.

Module Structure

The KVS module is organized into:

store.rs - Core implementation of the key-value store
error.rs - Error types specific to the KVS module
mod.rs - Module exports and public interface

Key Types

KvStore

The KvStore type represents an encrypted key-value store:

pub struct KvStore {
    // Private fields
    // ...
}

impl KvStore {
    // Create a new store
    pub fn new(name: &str, password: &str) -> Result<Self, CryptoError>;
    
    // Load a store from disk
    pub fn load(name: &str, password: &str) -> Result<Self, CryptoError>;
    
    // Save the store to disk
    pub fn save(&self) -> Result<(), CryptoError>;
    
    // Set a value
    pub fn set(&mut self, key: &str, value: &str) -> Result<(), CryptoError>;
    
    // Get a value
    pub fn get(&self, key: &str) -> Result<Option<String>, CryptoError>;
    
    // Delete a value
    pub fn delete(&mut self, key: &str) -> Result<(), CryptoError>;
    
    // Check if a key exists
    pub fn has(&self, key: &str) -> Result<bool, CryptoError>;
    
    // List all keys
    pub fn keys(&self) -> Result<Vec<String>, CryptoError>;
    
    // Clear all values
    pub fn clear(&mut self) -> Result<(), CryptoError>;
    
    // Get the name of the store
    pub fn name(&self) -> &str;
}

Key Features

Store Management

The module provides functionality for creating, loading, and managing key-value stores:

// Create a new store
let mut store = KvStore::new("my_store", "secure_password")?;

// Save the store to disk
store.save()?;

// Load a store from disk
let mut loaded_store = KvStore::load("my_store", "secure_password")?;

Value Management

The module provides functionality for managing values in the store:

// Set a value
store.set("api_key", "secret_api_key")?;

// Get a value
let api_key = store.get("api_key")?;

// Delete a value
store.delete("api_key")?;

// Check if a key exists
let exists = store.has("api_key")?;

// List all keys
let keys = store.keys()?;

// Clear all values
store.clear()?;

Technical Details

Encryption

The KVS module uses the Symmetric Encryption module to encrypt all values stored in the key-value store. This ensures that sensitive data is protected at rest.

The encryption process:

A master key is derived from the provided password using PBKDF2
Each value is encrypted using ChaCha20Poly1305 with a unique key derived from the master key and the value's key
The encrypted values are stored in a JSON file on disk

Storage Format

The key-value store is stored in a JSON file with the following structure:

{
  "name": "my_store",
  "salt": "base64-encoded-salt",
  "values": {
    "key1": "base64-encoded-encrypted-value",
    "key2": "base64-encoded-encrypted-value",
    ...
  }
}

The file is stored in the ~/.hero-vault/stores/ directory by default.

Security Considerations

Use strong passwords to protect the key-value store
The security of the store depends on the strength of the password
Consider the security implications of storing sensitive data on disk
Regularly backup the store to prevent data loss

Error Handling

The module uses the CryptoError type for handling errors that can occur during key-value store operations:

EncryptionFailed - Encryption failed
DecryptionFailed - Decryption failed
SerializationError - Serialization error

Examples

For examples of how to use the KVS module, see the examples/hero_vault directory. While there may not be specific examples for the KVS module, the general pattern of usage is similar to the key space management examples.

A basic usage example:

// Create a new store
let mut store = KvStore::new("my_store", "secure_password")?;

// Set some values
store.set("api_key", "secret_api_key")?;
store.set("access_token", "secret_access_token")?;

// Save the store to disk
store.save()?;

// Later, load the store
let loaded_store = KvStore::load("my_store", "secure_password")?;

// Get a value
let api_key = loaded_store.get("api_key")?;
println!("API Key: {}", api_key.unwrap_or_default());

to test

cargo test --lib vault::keypair

4.3 KiB Raw Blame History