herolib_rust/vault/src

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.

// 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.

// 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.

// 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.

// 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

// 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.

// 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.

// 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.