Hardware Security Module (HSM) Implementation Guide

Table of Contents

[AIR-3][AIS-3][AIT-3][AIP-3][RES-3]

Overview

This guide details the Hardware Security Module (HSM) implementation in Anya Core, designed to provide secure key management and cryptographic operations with multiple provider types including software, hardware, simulator, and Bitcoin-specific implementations.

Architecture

The HSM implementation follows the hexagonal architecture pattern with clean separation between:

  • Core Logic: Key management, cryptographic operations, audit logging
  • Providers: Interchangeable HSM implementations (Software, Hardware, Simulator, Bitcoin)
  • Configuration: Flexible configuration options for each provider
  • Client Interface: Unified API for all HSM operations
┌─────────────────────────────────────────────────────┐
│                  Client Applications                 │
└───────────────────────┬─────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────┐
│                    HSM Manager                       │
└───┬───────────────────┬─────────────────┬───────────┘
    │                   │                 │
┌───▼───────┐     ┌─────▼────────┐   ┌───▼───────────┐
│   Audit   │     │  Operations  │   │ Configuration │
│   Logger  │     │              │   │               │
└───────────┘     └──────────────┘   └───────────────┘
                         │
     ┌──────────────────┴───────────────────┐
     │                                      │
┌────▼───────┐ ┌────────▼─────┐ ┌──────────▼───────┐ ┌─────▼──────┐
│  Software  │ │   Hardware   │ │    Simulator     │ │   Bitcoin  │
│  Provider  │ │   Provider   │ │     Provider     │ │  Provider  │
└────────────┘ └──────────────┘ └──────────────────┘ └────────────┘

Provider Types

1. Software HSM Provider

The Software HSM provider implements a software-based key store for development and testing environments.

Key Features: - In-memory and file-based key storage - Support for multiple key types (RSA, EC, AES, Ed25519) - Session management with configurable timeouts - Encryption of stored keys - Support for Bitcoin test networks

Configuration:

software:
  token_dir: ".tokens"
  max_sessions: 10
  encryption_key: "secure-encryption-key"
  lock_timeout_seconds: 300
  use_testnet: true

2. Hardware HSM Provider

The Hardware HSM provider integrates with physical HSM devices such as YubiHSM, Ledger, and Trezor.

Key Features: - Support for multiple hardware device types - Hardware-backed key generation and storage - Secure communication with hardware devices - Timeout and retry handling - Support for Bitcoin operations

Configuration:

hardware:
  device_type: YubiHsm
  connection_string: "127.0.0.1:12345"
  auth_key_id: "key-id"
  password: null  # Set at runtime for security
  timeout_seconds: 30
  use_testnet: true

Supported Devices: - YubiHSM - Ledger - Trezor - Custom (extensible interface)

3. Simulator HSM Provider

The Simulator HSM provider simulates HSM functionality for testing environments.

Key Features: - Configurable latency simulation - Controllable failure scenarios - In-memory key storage - PIN protection simulation - Full HSM operation support

Configuration:

simulator:
  storage_path: ".simulator"
  simulate_latency: true
  latency_ms: 100
  simulate_failures: true
  failure_rate: 0.05
  pin_timeout_seconds: 300
  max_pin_attempts: 3
  use_testnet: true

4. Bitcoin HSM Provider

The Bitcoin HSM provider is specialized for Bitcoin operations with support for key derivation paths, address types, and Bitcoin-specific transactions.

Key Features: - BIP32 hierarchical deterministic wallet support - Multiple address types (P2PKH, P2WPKH, P2TR) - Taproot transaction support - Integration with Bitcoin networks (Mainnet, Testnet, Regtest, Signet) - Secure transaction signing

Configuration:

bitcoin:
  network: Testnet
  rpc_url: "http://127.0.0.1:18332"
  rpc_username: "username"
  rpc_password: "password"
  derivation_path_template: "m/84'/1'/0'/0/{index}"
  use_segwit: true
  use_taproot: true
  confirm_transactions: true
  default_fee_rate: 5

Key Management

Key Types Support

The HSM implementation supports multiple key types:

Key Type Description Supported Algorithms
RSA RSA key pairs with configurable sizes RSA-PKCS1, RSA-PSS, RSA-OAEP
EC Elliptic Curve keys with various curves ECDSA, ECDH
AES Symmetric AES keys with configurable sizes AES-CBC, AES-GCM, AES-CTR
Ed25519 Edwards-curve Digital Signature Algorithm EdDSA

Key Lifecycle

  1. Generation: Keys are generated within the HSM
  2. Storage: Private keys remain within the HSM, public keys can be exported
  3. Usage: Keys are used for cryptographic operations without exposing private material
  4. Rotation: Automatic key rotation based on configurable intervals
  5. Deletion: Secure key deletion with proper cleanup

Key Attributes

  • Key ID/Name
  • Key Type
  • Creation Date
  • Expiration Date
  • Usage Restrictions
  • Custom Metadata
  • Export Restrictions

Cryptographic Operations

Signing Operations

  • Digital Signatures: Generate signatures for data using various algorithms
  • Transaction Signing: Sign Bitcoin transactions with proper validation
  • Certificate Signing: Sign X.509 certificates
  • Message Signing: Sign arbitrary messages with identity verification

Encryption Operations

  • Data Encryption: Encrypt data using symmetric or asymmetric algorithms
  • Key Wrapping: Protect keys during transit or storage
  • Secure Communication: Establish secure communication channels

Verification Operations

  • Signature Verification: Verify signatures with stored public keys
  • Certificate Validation: Validate certificate chains
  • Identity Verification: Verify claimed identities

Audit and Compliance

Audit Logging

All HSM operations are logged with the following information:

  • Operation Type
  • Timestamp
  • User/Service Identity
  • Key Identifier (without exposing sensitive data)
  • Success/Failure Status
  • Error Information (if applicable)
  • Client IP Address/Identifier

Log Storage Options

  • File-based logging
  • Database logging
  • Syslog integration
  • Log forwarding to SIEM systems

Compliance Features

  • FIPS 140-2/3 compliance options
  • Common Criteria compliance
  • PCI-DSS requirements support
  • SOC2 audit support

Integration Example

use crate::security::hsm::{
    HsmConfig, HsmManager, 
    config::BitcoinConfig, 
    provider::HsmProviderType,
    config::BitcoinNetworkType,
};

async fn initialize_bitcoin_hsm() -> Result<HsmManager, HsmError> {
    // Create HSM configuration
    let config = HsmConfig {
        general: GeneralConfig {
            enabled: true,
            log_level: LogLevel::Info,
            operation_timeout: Duration::from_secs(30),
        },
        provider_type: HsmProviderType::BitcoinHsm,
        audit_enabled: true,
        bitcoin: BitcoinConfig {
            network: BitcoinNetworkType::Testnet,
            derivation_path_template: "m/84'/1'/0'/0/{index}".to_string(),
            use_segwit: true,
            use_taproot: true,
            confirm_transactions: true,
            default_fee_rate: 5,
            ..Default::default()
        },
        audit: AuditLoggerConfig {
            enabled: true,
            storage_type: AuditStorageType::File,
            file_path: Some("./logs/hsm_audit.log".to_string()),
            retention_days: 90,
            ..Default::default()
        },
        ..Default::default()
    };

    // Create HSM manager
    let mut hsm_manager = HsmManager::new(config).await?;

    // Initialize the HSM
    hsm_manager.initialize().await?;

    Ok(hsm_manager)
}

async fn sign_bitcoin_transaction(
    hsm_manager: &HsmManager,
    tx_data: &[u8],
    key_name: &str
) -> Result<Vec<u8>, HsmError> {
    // Sign the transaction
    hsm_manager.sign_data(
        key_name,
        tx_data,
        SignatureAlgorithm::EcdsaSha256
    ).await
}

Security Considerations

Key Protection

  • Private keys never leave the HSM
  • Keys are encrypted during storage
  • Access to keys is controlled via authentication
  • Key usage is restricted based on policies

Access Controls

  • Authentication required for HSM operations
  • Role-based access control for operation types
  • Multi-factor authentication for sensitive operations
  • Session management with timeouts

Physical Security

  • Hardware HSMs provide tamper resistance
  • Physical access controls for hardware devices
  • Environmental security (temperature, power, etc.)
  • Disaster recovery planning

Network Security

  • TLS for HSM communication
  • Client authentication for HSM connections
  • Network segmentation for HSM access
  • Firewall rules and access control lists

Performance Considerations

Throughput

  • Software HSM: 1,000-5,000 operations per second
  • Hardware HSM: 100-1,000 operations per second (device dependent)
  • Simulator HSM: Configurable based on testing needs
  • Bitcoin HSM: 50-200 operations per second (complexity dependent)

Latency

  • Software HSM: <5ms per operation
  • Hardware HSM: 10-100ms per operation (device dependent)
  • Simulator HSM: Configurable (default: 100ms)
  • Bitcoin HSM: 10-200ms per operation (complexity dependent)

Concurrency

  • Software HSM: Configurable max sessions (default: 10)
  • Hardware HSM: Device-dependent (typically 1-20 sessions)
  • Simulator HSM: Unlimited (for testing purposes)
  • Bitcoin HSM: Configurable (default: based on hardware constraints)

Future Enhancements

Planned Features

  1. Post-Quantum Cryptography: Support for algorithms resistant to quantum computing attacks
  2. Multi-Party Computation: Distributed key management across multiple HSMs
  3. Threshold Signatures: Support for k-of-n signing schemes
  4. Advanced Compliance: Enhanced audit capabilities for regulatory requirements
  5. Cloud HSM Integration: Support for cloud-based HSM services (AWS, GCP, Azure)

Roadmap Timeline

  • Q3 2025: Enhanced hardware vendor support
  • Q4 2025: Post-quantum algorithm integration
  • Q1 2026: Multi-party computation support
  • Q2 2026: Advanced threshold signature schemes

Conclusion

The Anya Core HSM implementation provides a secure, flexible foundation for cryptographic operations with multiple provider types. By following the hexagonal architecture pattern, it ensures clean separation of concerns and easy extensibility for future requirements.

The support for Bitcoin-specific operations makes it particularly valuable for blockchain applications, while the comprehensive audit capabilities ensure compliance with security best practices and regulatory requirements.

Last updated: 2025-05-30

See Also