161 lines
4.5 KiB
Markdown
161 lines
4.5 KiB
Markdown
# 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.
|