173 lines
4.3 KiB
Markdown
173 lines
4.3 KiB
Markdown
# 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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
// 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:
|
|
|
|
```rust
|
|
// 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:
|
|
|
|
1. A master key is derived from the provided password using PBKDF2
|
|
2. Each value is encrypted using ChaCha20Poly1305 with a unique key derived from the master key and the value's key
|
|
3. 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```rust
|
|
// 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
|
|
|
|
```bash
|
|
cargo test --lib vault::keypair
|
|
``` |