From 7298645368107f7303c55cadb705a64941d9b9c1 Mon Sep 17 00:00:00 2001 From: Sameh Abouelsaad Date: Sat, 10 May 2025 01:21:10 +0300 Subject: [PATCH] Add docs --- examples/hero_vault/README.md | 33 +++- .../hero_vault/agung_simple_transfer.rhai | 68 ------- src/hero_vault/README.md | 160 +++++++++++++++ src/hero_vault/ethereum/README.md | 160 +++++++++++++++ src/hero_vault/keypair/README.md | 187 ++++++++++++++++++ src/hero_vault/kvs/README.md | 167 ++++++++++++++++ src/hero_vault/symmetric/README.md | 98 +++++++++ 7 files changed, 796 insertions(+), 77 deletions(-) delete mode 100644 examples/hero_vault/agung_simple_transfer.rhai create mode 100644 src/hero_vault/README.md create mode 100644 src/hero_vault/ethereum/README.md create mode 100644 src/hero_vault/keypair/README.md create mode 100644 src/hero_vault/kvs/README.md create mode 100644 src/hero_vault/symmetric/README.md diff --git a/examples/hero_vault/README.md b/examples/hero_vault/README.md index 140b858..f0dc870 100644 --- a/examples/hero_vault/README.md +++ b/examples/hero_vault/README.md @@ -11,15 +11,18 @@ Hero Vault provides cryptographic operations including: - Digital signatures (signing and verification) - Symmetric encryption (key generation, encryption, decryption) - Ethereum wallet functionality +- Smart contract interactions +- Key-value store with encryption -## Directory Structure +## Example Files -- `rhai/` - Rhai script examples demonstrating Hero Vault functionality - - `example.rhai` - Basic example demonstrating key management, signing, and encryption - - `advanced_example.rhai` - Advanced example with error handling and more complex operations - - `key_persistence_example.rhai` - Demonstrates creating and saving a key space to disk - - `load_existing_space.rhai` - Shows how to load a previously created key space and use its keypairs - - `README.md` - Documentation for the Rhai scripting API +- `example.rhai` - Basic example demonstrating key management, signing, and encryption +- `advanced_example.rhai` - Advanced example with error handling, conditional logic, and more complex operations +- `key_persistence_example.rhai` - Demonstrates creating and saving a key space to disk +- `load_existing_space.rhai` - Shows how to load a previously created key space and use its keypairs +- `contract_example.rhai` - Demonstrates loading a contract ABI and interacting with smart contracts +- `agung_send_transaction.rhai` - Demonstrates sending native tokens on the Agung network +- `agung_contract_with_args.rhai` - Shows how to interact with contracts with arguments on Agung ## Running the Examples @@ -27,7 +30,7 @@ You can run the examples using the `herodo` tool that comes with the SAL project ```bash # Run a single example -herodo --path rhai/example.rhai +herodo --path example.rhai # Run all examples using the provided script ./run_examples.sh @@ -37,6 +40,16 @@ herodo --path rhai/example.rhai Key spaces are stored in the `~/.hero-vault/key-spaces/` directory by default. Each key space is stored in a separate JSON file named after the key space (e.g., `my_space.json`). +## Ethereum Functionality + +The Hero Vault module provides comprehensive Ethereum wallet functionality: + +- Creating and managing wallets for different networks +- Sending ETH transactions +- Checking balances +- Interacting with smart contracts (read and write functions) +- Support for multiple networks (Ethereum, Gnosis, Peaq, Agung, etc.) + ## Security Key spaces are encrypted with ChaCha20Poly1305 using a key derived from the provided password. The encryption ensures that the key material is secure at rest. @@ -46,4 +59,6 @@ Key spaces are encrypted with ChaCha20Poly1305 using a key derived from the prov 1. **Use Strong Passwords**: Since the security of your key spaces depends on the strength of your passwords, use strong, unique passwords. 2. **Backup Key Spaces**: Regularly backup your key spaces directory to prevent data loss. 3. **Script Organization**: Split your scripts into logical units, with separate scripts for key creation and key usage. -4. **Error Handling**: Always check the return values of functions to ensure operations succeeded before proceeding. \ No newline at end of file +4. **Error Handling**: Always check the return values of functions to ensure operations succeeded before proceeding. +5. **Network Selection**: When working with Ethereum functionality, be explicit about which network you're targeting to avoid confusion. +6. **Gas Management**: For Ethereum transactions, consider gas costs and set appropriate gas limits. diff --git a/examples/hero_vault/agung_simple_transfer.rhai b/examples/hero_vault/agung_simple_transfer.rhai deleted file mode 100644 index b8e50b8..0000000 --- a/examples/hero_vault/agung_simple_transfer.rhai +++ /dev/null @@ -1,68 +0,0 @@ -// Example Rhai script for testing a simple ETH transfer on Agung network -// This script demonstrates how to use send_eth with the private key - -// Step 1: Set up wallet and network -let space_name = "agung_simple_transfer_demo"; -let password = "secure_password123"; -let private_key = "0xf3976cfd4e0705cf90014f18140c14850bee210d4d609d49eb84eecc36fc5f38"; -let network_name = "agung"; - -print("=== Testing Simple ETH Transfer on Agung Network ===\n"); - -// Create a key space -print("Creating key space: " + space_name); -if create_key_space(space_name, password) { - print("✓ Key space created successfully"); - - // Create a keypair - print("\nCreating keypair..."); - if create_keypair("transfer_key", password) { - print("✓ Created contract keypair"); - - // Create a wallet from the private key for the Agung network - print("\nCreating wallet from private key for Agung network..."); - if create_wallet_from_private_key_for_network(private_key, network_name) { - print("✓ Wallet created successfully"); - - // Get the wallet address - let wallet_address = get_wallet_address_for_network(network_name); - print("Wallet address: " + wallet_address); - - // Check wallet balance - print("\nChecking wallet balance..."); - let balance = get_balance(network_name, wallet_address); - if balance != "" { - print("Wallet balance: " + balance + " wei"); - - // Define a recipient address for the transfer - // Using a random valid address on the network - let recipient = "0x7267B587E4416537060C6bF0B06f6Fd421106650"; - let amount = "1000000000000000"; // 0.001 ETH - - print("\nAttempting to transfer " + amount + " wei to " + recipient); - - // Send ETH - let tx_hash = send_eth(network_name, recipient, amount); - - if tx_hash != "" { - print("✓ Transaction sent successfully"); - print("Transaction hash: " + tx_hash); - print("You can view the transaction at: " + get_network_explorer_url(network_name) + "/tx/" + tx_hash); - } else { - print("✗ Failed to send transaction"); - print("This could be due to insufficient funds or other errors."); - } - } else { - print("✗ Failed to get wallet balance"); - } - } else { - print("✗ Failed to create wallet from private key"); - } - } else { - print("✗ Failed to create keypair"); - } -} else { - print("✗ Failed to create key space"); -} - -print("\nSimple transfer test completed"); diff --git a/src/hero_vault/README.md b/src/hero_vault/README.md new file mode 100644 index 0000000..28a3f1b --- /dev/null +++ b/src/hero_vault/README.md @@ -0,0 +1,160 @@ +# Hero Vault Cryptography Module + +The Hero Vault module provides comprehensive cryptographic functionality for the SAL project, including key management, digital signatures, symmetric encryption, Ethereum wallet operations, and a secure key-value store. + +## Module Structure + +The Hero Vault module is organized into several submodules: + +- `error.rs` - Error types for cryptographic operations +- `keypair/` - ECDSA keypair management functionality +- `symmetric/` - Symmetric encryption using ChaCha20Poly1305 +- `ethereum/` - Ethereum wallet and smart contract functionality +- `kvs/` - Encrypted key-value store + +## Key Features + +### Key Space Management + +The module provides functionality for creating, loading, and managing key spaces. A key space is a secure container for cryptographic keys, which can be encrypted and stored on disk. + +```rust +// Create a new key space +let space = KeySpace::new("my_space", "secure_password")?; + +// Save the key space to disk +space.save()?; + +// Load a key space from disk +let loaded_space = KeySpace::load("my_space", "secure_password")?; +``` + +### Keypair Management + +The module provides functionality for creating, selecting, and using ECDSA keypairs for digital signatures. + +```rust +// Create a new keypair in the active key space +let keypair = space.create_keypair("my_keypair", "secure_password")?; + +// Select a keypair for use +space.select_keypair("my_keypair")?; + +// List all keypairs in the active key space +let keypairs = space.list_keypairs()?; +``` + +### Digital Signatures + +The module provides functionality for signing and verifying messages using ECDSA. + +```rust +// Sign a message using the selected keypair +let signature = space.sign("This is a message to sign")?; + +// Verify a signature +let is_valid = space.verify("This is a message to sign", &signature)?; +``` + +### Symmetric Encryption + +The module provides functionality for symmetric encryption using ChaCha20Poly1305. + +```rust +// Generate a new symmetric key +let key = space.generate_key()?; + +// Encrypt a message +let encrypted = space.encrypt(&key, "This is a secret message")?; + +// Decrypt a message +let decrypted = space.decrypt(&key, &encrypted)?; +``` + +### Ethereum Wallet Functionality + +The module provides comprehensive Ethereum wallet functionality, including: + +- Creating and managing wallets for different networks +- Sending ETH transactions +- Checking balances +- Interacting with smart contracts + +```rust +// Create an Ethereum wallet +let wallet = EthereumWallet::new(keypair)?; + +// Get the wallet address +let address = wallet.get_address()?; + +// Send ETH +let tx_hash = wallet.send_eth("0x1234...", "1000000000000000")?; + +// Check balance +let balance = wallet.get_balance("0x1234...")?; +``` + +### Smart Contract Interactions + +The module provides functionality for interacting with smart contracts on EVM-based blockchains. + +```rust +// Load a contract ABI +let contract = Contract::new(provider, "0x1234...", abi)?; + +// Call a read-only function +let result = contract.call_read("balanceOf", vec!["0x5678..."])?; + +// Call a write function +let tx_hash = contract.call_write("transfer", vec!["0x5678...", "1000"])?; +``` + +### Key-Value Store + +The module provides an encrypted key-value store for securely storing sensitive data. + +```rust +// Create a new store +let store = KvStore::new("my_store", "secure_password")?; + +// Set a value +store.set("api_key", "secret_api_key")?; + +// Get a value +let api_key = store.get("api_key")?; +``` + +## Error Handling + +The module uses a comprehensive error type (`CryptoError`) for handling errors that can occur during cryptographic operations: + +- `InvalidKeyLength` - Invalid key length +- `EncryptionFailed` - Encryption failed +- `DecryptionFailed` - Decryption failed +- `SignatureFormatError` - Signature format error +- `KeypairAlreadyExists` - Keypair already exists +- `KeypairNotFound` - Keypair not found +- `NoActiveSpace` - No active key space +- `NoKeypairSelected` - No keypair selected +- `SerializationError` - Serialization error +- `InvalidAddress` - Invalid address format +- `ContractError` - Smart contract error + +## Ethereum Networks + +The module supports multiple Ethereum networks, including: + +- Gnosis Chain +- Peaq Network +- Agung Network + +## Security Considerations + +- Key spaces are encrypted with ChaCha20Poly1305 using a key derived from the provided password +- Private keys are never stored in plaintext +- The module uses secure random number generation for key creation +- All cryptographic operations use well-established libraries and algorithms + +## Examples + +For examples of how to use the Hero Vault module, see the `examples/hero_vault` directory. diff --git a/src/hero_vault/ethereum/README.md b/src/hero_vault/ethereum/README.md new file mode 100644 index 0000000..34fb2dd --- /dev/null +++ b/src/hero_vault/ethereum/README.md @@ -0,0 +1,160 @@ +# Hero Vault Ethereum Module + +The Ethereum module provides functionality for creating and managing Ethereum wallets and interacting with smart contracts on EVM-based blockchains. + +## Module Structure + +The Ethereum module is organized into several components: + +- `wallet.rs` - Core Ethereum wallet implementation +- `networks.rs` - Network registry and configuration +- `provider.rs` - Provider creation and management +- `transaction.rs` - Transaction-related functionality +- `storage.rs` - Wallet storage functionality +- `contract.rs` - Smart contract interaction functionality +- `contract_utils.rs` - Utilities for contract interactions + +## Key Features + +### Wallet Management + +The module provides functionality for creating and managing Ethereum wallets: + +```rust +// Create a new Ethereum wallet for a specific network +let wallet = create_ethereum_wallet_for_network("Ethereum")?; + +// Create a wallet for specific networks +let peaq_wallet = create_peaq_wallet()?; +let agung_wallet = create_agung_wallet()?; + +// Create a wallet with a specific name +let named_wallet = create_ethereum_wallet_from_name_for_network("my_wallet", "Gnosis")?; + +// Create a wallet from a private key +let imported_wallet = create_ethereum_wallet_from_private_key("0x...")?; + +// Get the current wallet for a network +let current_wallet = get_current_ethereum_wallet_for_network("Ethereum")?; + +// Clear wallets +clear_ethereum_wallets()?; +clear_ethereum_wallets_for_network("Gnosis")?; +``` + +### Network Management + +The module supports multiple Ethereum networks and provides functionality for managing network configurations: + +```rust +// Get a network configuration by name +let network = get_network_by_name("Ethereum")?; + +// Get the proper network name (normalized) +let name = get_proper_network_name("eth")?; // Returns "Ethereum" + +// List all available network names +let networks = list_network_names()?; + +// Get all network configurations +let all_networks = get_all_networks()?; +``` + +### Provider Management + +The module provides functionality for creating and managing Ethereum providers: + +```rust +// Create a provider for a specific network +let provider = create_provider("Ethereum")?; + +// Create providers for specific networks +let gnosis_provider = create_gnosis_provider()?; +let peaq_provider = create_peaq_provider()?; +let agung_provider = create_agung_provider()?; +``` + +### Transaction Management + +The module provides functionality for managing Ethereum transactions: + +```rust +// Get the balance of an address +let balance = get_balance("Ethereum", "0x...")?; + +// Send ETH to an address +let tx_hash = send_eth("Ethereum", "0x...", "1000000000000000")?; + +// Format a balance for display +let formatted = format_balance(balance, 18)?; // Convert wei to ETH +``` + +### Smart Contract Interactions + +The module provides functionality for interacting with smart contracts: + +```rust +// Load a contract ABI from JSON +let abi = load_abi_from_json(json_string)?; + +// Create a contract instance +let contract = Contract::new(provider, "0x...", abi)?; + +// Call a read-only function +let result = call_read_function(contract, "balanceOf", vec!["0x..."])?; + +// Call a write function +let tx_hash = call_write_function(contract, "transfer", vec!["0x...", "1000"])?; + +// Estimate gas for a function call +let gas = estimate_gas(contract, "transfer", vec!["0x...", "1000"])?; +``` + +### Contract Utilities + +The module provides utilities for working with contract function arguments and return values: + +```rust +// Convert Rhai values to Ethereum tokens +let token = convert_rhai_to_token(value)?; + +// Prepare function arguments +let args = prepare_function_arguments(function, vec![arg1, arg2])?; + +// Convert Ethereum tokens to Rhai values +let rhai_value = convert_token_to_rhai(token)?; + +// Convert a token to a dynamic value +let dynamic = token_to_dynamic(token)?; +``` + +## Supported Networks + +The module supports multiple Ethereum networks, including: + +- Gnosis Chain +- Peaq Network +- Agung Network + +Each network has its own configuration, including: + +- RPC URL +- Chain ID +- Explorer URL +- Native currency symbol and decimals + +## Error Handling + +The module uses the `CryptoError` type for handling errors that can occur during Ethereum operations: + +- `InvalidAddress` - Invalid Ethereum address format +- `ContractError` - Smart contract interaction error + +## Examples + +For examples of how to use the Ethereum module, see the `examples/hero_vault` directory, particularly: + +- `contract_example.rhai` - Demonstrates loading a contract ABI and interacting with smart contracts +- `agung_simple_transfer.rhai` - Shows how to perform a simple ETH transfer on the Agung network +- `agung_send_transaction.rhai` - Demonstrates sending transactions on the Agung network +- `agung_contract_with_args.rhai` - Shows how to interact with contracts with arguments on Agung diff --git a/src/hero_vault/keypair/README.md b/src/hero_vault/keypair/README.md new file mode 100644 index 0000000..b89f9cf --- /dev/null +++ b/src/hero_vault/keypair/README.md @@ -0,0 +1,187 @@ +# Hero Vault Keypair Module + +The Keypair module provides functionality for creating, managing, and using ECDSA keypairs for digital signatures and other cryptographic operations. + +## Module Structure + +The Keypair module is organized into: + +- `implementation.rs` - Core implementation of the KeyPair and KeySpace types +- `mod.rs` - Module exports and public interface + +## Key Types + +### KeyPair + +The `KeyPair` type represents an ECDSA keypair used for digital signatures and other cryptographic operations. + +```rust +pub struct KeyPair { + // Private fields + // ... +} + +impl KeyPair { + // Create a new random keypair + pub fn new() -> Result; + + // Create a keypair from an existing private key + pub fn from_private_key(private_key: &[u8]) -> Result; + + // Get the public key + pub fn public_key(&self) -> &[u8]; + + // Sign a message + pub fn sign(&self, message: &[u8]) -> Result, CryptoError>; + + // Verify a signature + pub fn verify(&self, message: &[u8], signature: &[u8]) -> Result; + + // Derive an Ethereum address from the public key + pub fn to_ethereum_address(&self) -> Result; + + // Export the private key (should be used with caution) + pub fn export_private_key(&self) -> Result, CryptoError>; +} +``` + +### KeySpace + +The `KeySpace` type represents a secure container for multiple keypairs, which can be encrypted and stored on disk. + +```rust +pub struct KeySpace { + // Private fields + // ... +} + +impl KeySpace { + // Create a new key space + pub fn new(name: &str, password: &str) -> Result; + + // Load a key space from disk + pub fn load(name: &str, password: &str) -> Result; + + // Save the key space to disk + pub fn save(&self) -> Result<(), CryptoError>; + + // Create a new keypair in the key space + pub fn create_keypair(&mut self, name: &str, password: &str) -> Result<&KeyPair, CryptoError>; + + // Select a keypair for use + pub fn select_keypair(&mut self, name: &str) -> Result<&KeyPair, CryptoError>; + + // Get the currently selected keypair + pub fn current_keypair(&self) -> Result<&KeyPair, CryptoError>; + + // List all keypairs in the key space + pub fn list_keypairs(&self) -> Result, CryptoError>; + + // Get a keypair by name + pub fn get_keypair(&self, name: &str) -> Result<&KeyPair, CryptoError>; + + // Remove a keypair from the key space + pub fn remove_keypair(&mut self, name: &str) -> Result<(), CryptoError>; + + // Rename a keypair + pub fn rename_keypair(&mut self, old_name: &str, new_name: &str) -> Result<(), CryptoError>; + + // Get the name of the key space + pub fn name(&self) -> &str; +} +``` + +## Key Features + +### Key Space Management + +The module provides functionality for creating, loading, and managing key spaces: + +```rust +// Create a new key space +let mut space = KeySpace::new("my_space", "secure_password")?; + +// Save the key space to disk +space.save()?; + +// Load a key space from disk +let mut loaded_space = KeySpace::load("my_space", "secure_password")?; +``` + +### Keypair Management + +The module provides functionality for creating, selecting, and using keypairs: + +```rust +// Create a new keypair in the key space +let keypair = space.create_keypair("my_keypair", "secure_password")?; + +// Select a keypair for use +space.select_keypair("my_keypair")?; + +// Get the currently selected keypair +let current = space.current_keypair()?; + +// List all keypairs in the key space +let keypairs = space.list_keypairs()?; + +// Get a keypair by name +let keypair = space.get_keypair("my_keypair")?; + +// Remove a keypair from the key space +space.remove_keypair("my_keypair")?; + +// Rename a keypair +space.rename_keypair("my_keypair", "new_name")?; +``` + +### Digital Signatures + +The module provides functionality for signing and verifying messages using ECDSA: + +```rust +// Sign a message using the selected keypair +let keypair = space.current_keypair()?; +let signature = keypair.sign("This is a message to sign".as_bytes())?; + +// Verify a signature +let is_valid = keypair.verify("This is a message to sign".as_bytes(), &signature)?; +``` + +### Ethereum Address Derivation + +The module provides functionality for deriving Ethereum addresses from keypairs: + +```rust +// Derive an Ethereum address from a keypair +let keypair = space.current_keypair()?; +let address = keypair.to_ethereum_address()?; +``` + +## Security Considerations + +- Key spaces are encrypted with ChaCha20Poly1305 using a key derived from the provided password +- Private keys are never stored in plaintext +- The module uses secure random number generation for key creation +- All cryptographic operations use well-established libraries and algorithms + +## Error Handling + +The module uses the `CryptoError` type for handling errors that can occur during keypair operations: + +- `InvalidKeyLength` - Invalid key length +- `SignatureFormatError` - Signature format error +- `KeypairAlreadyExists` - Keypair already exists +- `KeypairNotFound` - Keypair not found +- `NoActiveSpace` - No active key space +- `NoKeypairSelected` - No keypair selected +- `SerializationError` - Serialization error + +## Examples + +For examples of how to use the Keypair module, see the `examples/hero_vault` directory, particularly: + +- `example.rhai` - Basic example demonstrating key management and signing +- `advanced_example.rhai` - Advanced example with error handling +- `key_persistence_example.rhai` - Demonstrates creating and saving a key space to disk +- `load_existing_space.rhai` - Shows how to load a previously created key space diff --git a/src/hero_vault/kvs/README.md b/src/hero_vault/kvs/README.md new file mode 100644 index 0000000..89d6d2e --- /dev/null +++ b/src/hero_vault/kvs/README.md @@ -0,0 +1,167 @@ +# 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; + + // Load a store from disk + pub fn load(name: &str, password: &str) -> Result; + + // 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, 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; + + // List all keys + pub fn keys(&self) -> Result, 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()); +``` diff --git a/src/hero_vault/symmetric/README.md b/src/hero_vault/symmetric/README.md new file mode 100644 index 0000000..18359ec --- /dev/null +++ b/src/hero_vault/symmetric/README.md @@ -0,0 +1,98 @@ +# Hero Vault Symmetric Encryption Module + +The Symmetric Encryption module provides functionality for symmetric encryption and decryption using the ChaCha20Poly1305 algorithm. + +## Module Structure + +The Symmetric Encryption module is organized into: + +- `implementation.rs` - Core implementation of symmetric encryption functionality +- `mod.rs` - Module exports and public interface + +## Key Features + +### Key Generation + +The module provides functionality for generating secure symmetric keys: + +```rust +// Generate a new symmetric key +let key = generate_key()?; +``` + +### Encryption + +The module provides functionality for encrypting data using ChaCha20Poly1305: + +```rust +// Encrypt data +let encrypted = encrypt(&key, "This is a secret message")?; +``` + +### Decryption + +The module provides functionality for decrypting data encrypted with ChaCha20Poly1305: + +```rust +// Decrypt data +let decrypted = decrypt(&key, &encrypted)?; +``` + +### Password-Based Key Derivation + +The module provides functionality for deriving encryption keys from passwords: + +```rust +// Derive a key from a password +let key = derive_key_from_password(password, salt)?; +``` + +## Technical Details + +### ChaCha20Poly1305 + +The module uses the ChaCha20Poly1305 authenticated encryption with associated data (AEAD) algorithm, which provides both confidentiality and integrity protection. + +ChaCha20 is a stream cipher designed by Daniel J. Bernstein, which is combined with the Poly1305 message authentication code to provide authenticated encryption. + +Key features of ChaCha20Poly1305: + +- 256-bit key +- 96-bit nonce (used once) +- Authentication tag to verify integrity +- High performance on modern processors +- Resistance to timing attacks + +### Key Derivation + +For password-based encryption, the module uses the PBKDF2 (Password-Based Key Derivation Function 2) algorithm to derive encryption keys from passwords. + +Key features of PBKDF2: + +- Configurable iteration count to increase computational cost +- Salt to prevent rainbow table attacks +- Configurable output key length +- Uses HMAC-SHA256 as the underlying pseudorandom function + +## Security Considerations + +- Always use a unique key for each encryption operation +- Never reuse nonces with the same key +- Store keys securely +- Use strong passwords for password-based encryption +- Consider the security implications of storing encrypted data + +## Error Handling + +The module uses the `CryptoError` type for handling errors that can occur during symmetric encryption operations: + +- `InvalidKeyLength` - Invalid key length +- `EncryptionFailed` - Encryption failed +- `DecryptionFailed` - Decryption failed + +## Examples + +For examples of how to use the Symmetric Encryption module, see the `examples/hero_vault` directory, particularly: + +- `example.rhai` - Basic example demonstrating symmetric encryption +- `advanced_example.rhai` - Advanced example with error handling