sal/src/hero_vault/keypair

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.

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

impl KeyPair {
    // Create a new random keypair
    pub fn new() -> Result<Self, CryptoError>;
    
    // Create a keypair from an existing private key
    pub fn from_private_key(private_key: &[u8]) -> Result<Self, CryptoError>;
    
    // Get the public key
    pub fn public_key(&self) -> &[u8];
    
    // Sign a message
    pub fn sign(&self, message: &[u8]) -> Result<Vec<u8>, CryptoError>;
    
    // Verify a signature
    pub fn verify(&self, message: &[u8], signature: &[u8]) -> Result<bool, CryptoError>;
    
    // Derive an Ethereum address from the public key
    pub fn to_ethereum_address(&self) -> Result<String, CryptoError>;
    
    // Export the private key (should be used with caution)
    pub fn export_private_key(&self) -> Result<Vec<u8>, CryptoError>;
}

KeySpace

The KeySpace type represents a secure container for multiple keypairs, which can be encrypted and stored on disk.

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

impl KeySpace {
    // Create a new key space
    pub fn new(name: &str, password: &str) -> Result<Self, CryptoError>;
    
    // Load a key space from disk
    pub fn load(name: &str, password: &str) -> Result<Self, CryptoError>;
    
    // 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<Vec<String>, 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:

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

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

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

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