HeliosDB Security Module

HeliosDB Security Module

Enterprise-grade security features for HeliosDB, including Transparent Data Encryption (TDE), key management, and HSM/KMS integration.

Features

Transparent Data Encryption (TDE)

• Multiple Algorithms: AES-256-GCM (default), AES-256-CTR, ChaCha20-Poly1305
• Key Hierarchy: Master Encryption Key (MEK) → Table Encryption Keys (TEK)
• Hardware Acceleration: Automatic AES-NI detection and usage
• Authenticated Encryption: Built-in authentication with GCM and Poly1305
• Zero-Copy Operations: Efficient data handling with bytes::Bytes

Key Management

• MEK/TEK Hierarchy: Two-tier key architecture for security and flexibility
• Automatic Key Rotation: Support for key rotation without downtime
• Key Caching: LRU-based in-memory key cache
• Secure Key Storage: Encrypted key envelopes on disk
• Key Versioning: Track key versions for compliance

HSM Integration

• PKCS#11 Support: Compatible with any PKCS#11-compliant HSM
• Hardware Security: Keys generated and stored in tamper-resistant hardware
• Tested with:
  • Thales Luna HSM
  • AWS CloudHSM
  • SoftHSM2 (for testing)

Cloud KMS Support

• AWS KMS: Native integration with AWS Key Management Service
• Azure Key Vault: Support for Azure cloud key management
• HashiCorp Vault: Transit secrets engine integration

Security Features

• Automatic Key Zeroization: Memory cleared on key destruction
• Secure Random Generation: Cryptographically secure RNG
• FIPS 140-2 Compliance: Optional FIPS mode (feature flag)
• Audit Trail: Comprehensive logging of all security operations

Installation

Add to your Cargo.toml:

[dependencies]
heliosdb-security = { path = "../heliosdb-security" }

# Optional: Enable cloud KMS providers
heliosdb-security = { path = "../heliosdb-security", features = ["aws-kms"] }

Quick Start

Basic TDE Usage

use heliosdb_security::tde::{TdeSubsystem, TdeConfig, EncryptionAlgorithm};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = TdeConfig {
        enabled: true,
        algorithm: EncryptionAlgorithm::Aes256Gcm,
        key_storage_path: PathBuf::from("/var/lib/heliosdb/keys"),
        default_mek_id: "master_key_001".to_string(),
        cache_limit: 1000,
        kms_config: None,
        hsm_config: None,
    };

    let tde = TdeSubsystem::new(config).await?;

    // Encrypt data
    let plaintext = b"Sensitive user data";
    let encrypted = tde.encrypt_table_data("users", plaintext, None).await?;

    // Decrypt data
    let decrypted = tde.decrypt_table_data("users", &encrypted).await?;
    assert_eq!(plaintext, &decrypted[..]);

    Ok(())
}

Using AWS KMS

use heliosdb_security::tde::{TdeConfig, KmsConfig, AwsKmsConfig, EncryptionAlgorithm};

let config = TdeConfig {
    enabled: true,
    algorithm: EncryptionAlgorithm::Aes256Gcm,
    kms_config: Some(KmsConfig::Aws(AwsKmsConfig {
        region: "us-east-1".to_string(),
        key_id: "arn:aws:kms:us-east-1:123456789:key/abc-def-ghi".to_string(),
        ..Default::default()
    })),
    ..Default::default()
};

Using HSM (PKCS#11)

use heliosdb_security::tde::{TdeConfig, HsmConfig, EncryptionAlgorithm};

let config = TdeConfig {
    enabled: true,
    algorithm: EncryptionAlgorithm::Aes256Gcm,
    hsm_config: Some(HsmConfig {
        pkcs11_library_path: "/usr/lib/softhsm/libsofthsm2.so".to_string(),
        slot_id: 0,
        pin: "1234".to_string(),
        token_label: Some("heliosdb".to_string()),
        timeout_secs: 30,
        enable_logging: true,
    }),
    ..Default::default()
};

Architecture

Key Hierarchy

Master Encryption Key (MEK)
  ├─ Stored in HSM or KMS (never on disk)
  └─ Used to encrypt/decrypt TEKs
      │
      ├─> Table Encryption Key 1 (TEK-1)
      │     └─ Encrypts: user_table SSTables
      │
      ├─> Table Encryption Key 2 (TEK-2)
      │     └─ Encrypts: orders_table SSTables
      │
      └─> Table Encryption Key N (TEK-N)
            └─ Encrypts: vector_index HNSW data

Encryption Flow

Plaintext Data
    │
    ├─> [TDE Engine]
    │      │
    │      ├─> Generate random nonce
    │      ├─> Fetch TEK from Key Manager
    │      ├─> Encrypt with AES-256-GCM
    │      └─> Return EncryptedBlock
    │
Encrypted Data (stored on disk)

Decryption Flow

Encrypted Data (from disk)
    │
    ├─> [TDE Engine]
    │      │
    │      ├─> Extract nonce and ciphertext
    │      ├─> Fetch TEK from Key Manager (or cache)
    │      ├─> Decrypt with AES-256-GCM
    │      ├─> Verify authentication tag
    │      └─> Return plaintext
    │
Plaintext Data (in memory)

Configuration

Environment Variables

# Enable TDE
HELIOSDB_TDE_ENABLED=true

# Set encryption algorithm
HELIOSDB_TDE_ALGORITHM=aes256-gcm

# Key storage path
HELIOSDB_KEY_STORAGE_PATH=/var/lib/heliosdb/keys

# AWS KMS (optional)
AWS_REGION=us-east-1
AWS_KMS_KEY_ID=arn:aws:kms:us-east-1:123456789:key/abc

# HSM (optional)
HELIOSDB_HSM_PKCS11_LIB=/usr/lib/softhsm/libsofthsm2.so
HELIOSDB_HSM_SLOT_ID=0
HELIOSDB_HSM_PIN=1234

Configuration File (YAML)

security:
  tde_enabled: true
  tde_algorithm: aes256-gcm
  key_storage_path: /var/lib/heliosdb/keys
  default_mek_id: master_key_001
  key_cache_limit: 1000

  # AWS KMS
  kms_provider:
    aws:
      region: us-east-1
      key_id: arn:aws:kms:us-east-1:123456789:key/abc

  # Or HSM
  hsm_enabled: true
  hsm_pkcs11_library: /usr/lib/softhsm/libsofthsm2.so
  hsm_slot_id: 0

Performance

Encryption Overhead

Operation	Without TDE	With TDE (AES-GCM)	Overhead
Point Read	0.8ms	0.95ms	+18%
Bulk Insert	100K rows/sec	85K rows/sec	-15%
Full Scan	2GB/sec	1.7GB/sec	-15%
Vector Search	25ms	28ms	+12%

Note: With hardware AES-NI acceleration, overhead is reduced to <5%.

Key Cache Performance

• Cache Hit: <0.1ms
• Cache Miss (disk load): 1-2ms
• Cache Miss (HSM/KMS): 10-50ms

Security Considerations

Best Practices

1. Use HSM or Cloud KMS in Production

   • Never use InMemoryMekProvider in production
   • HSM provides hardware-backed key security
   • Cloud KMS offers managed key lifecycle

2. Rotate Keys Regularly

   • Rotate TEKs annually
   • Rotate MEKs every 2 years
   • Automate rotation with scheduled jobs

3. Monitor Key Access

   • Enable audit logging
   • Alert on unusual key access patterns
   • Review logs regularly

4. Secure Key Storage Path

   • Restrict filesystem permissions (0600)
   • Use encrypted filesystem
   • Regular backups of key envelopes

5. Use Strong PINs/Passwords

   • HSM PIN: minimum 8 characters
   • Rotate HSM PINs quarterly
   • Never hardcode credentials

Compliance

• GDPR: Article 32 (Encryption of personal data)
• HIPAA: 164.312(a)(2)(iv) (Encryption and decryption)
• PCI-DSS: Requirement 3.4 (Encryption of cardholder data)
• SOC 2: CC6.7 (Encryption of data at rest)

Testing

Run Unit Tests

cargo test -p heliosdb-security

Run HSM Tests (requires SoftHSM2)

# Install SoftHSM2
apt-get install softhsm2

# Initialize token
softhsm2-util --init-token --slot 0 --label "test" --pin 1234 --so-pin 5678

# Run tests
cargo test -p heliosdb-security --features hsm -- --include-ignored

Run Examples

cargo run --example basic_tde

Troubleshooting

HSM Connection Issues

Error: Failed to load PKCS#11 library: /usr/lib/softhsm/libsofthsm2.so

Solution: Install SoftHSM2 or update library path.

AWS KMS Authentication

Error: AWS KMS encryption failed: InvalidCredentials

Solution: Configure AWS credentials:

aws configure
# or
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...

Key Not Found

Error: key not found: tek_users_...

Solution: Ensure key storage path exists and has correct permissions.

Contributing

See the main CONTRIBUTING.md for guidelines.

License

Apache-2.0