TDE Quick Reference Guide

TDE Quick Reference Guide

Quick Start (5 minutes)

1. Basic Setup

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

let config = TdeConfig {
    enabled: true,
    algorithm: EncryptionAlgorithm::Aes256Gcm,
    ..Default::default()
};

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

2. Encrypt Data

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

3. Decrypt Data

let decrypted = tde.decrypt_table_data("users", &encrypted).await?;

Common Configurations

Development (In-Memory)

TdeConfig {
    enabled: true,
    algorithm: EncryptionAlgorithm::Aes256Gcm,
    key_storage_path: PathBuf::from("/tmp/heliosdb/keys"),
    default_mek_id: "dev_mek".to_string(),
    cache_limit: 100,
    kms_config: None,
    hsm_config: None,
}

Production (AWS KMS)

TdeConfig {
    enabled: true,
    algorithm: EncryptionAlgorithm::Aes256Gcm,
    key_storage_path: PathBuf::from("/var/lib/heliosdb/keys"),
    default_mek_id: "prod_mek_001".to_string(),
    cache_limit: 1000,
    kms_config: Some(KmsConfig::Aws(AwsKmsConfig {
        region: "us-east-1".to_string(),
        key_id: "arn:aws:kms:us-east-1:123456789:key/abc".to_string(),
        ..Default::default()
    })),
    hsm_config: None,
}

Production (HSM)

TdeConfig {
    enabled: true,
    algorithm: EncryptionAlgorithm::Aes256Gcm,
    key_storage_path: PathBuf::from("/var/lib/heliosdb/keys"),
    default_mek_id: "hsm_mek_001".to_string(),
    cache_limit: 1000,
    kms_config: None,
    hsm_config: Some(HsmConfig {
        pkcs11_library_path: "/usr/lib/softhsm/libsofthsm2.so".to_string(),
        slot_id: 0,
        pin: env::var("HSM_PIN").unwrap(),
        token_label: Some("heliosdb".to_string()),
        timeout_secs: 30,
        enable_logging: true,
    }),
}

Common Operations

Generate Table Key

let key_id = key_manager.generate_table_key("users", None).await?;

Rotate Key

let new_key_id = tde.rotate_table_key("users").await?;

List Keys

let keys = key_manager.list_keys(Some(KeyType::Table)).await?;
for key in keys {
    println!("Key: {}, Table: {}", key.key_id, key.object_name.unwrap());
}

Get Statistics

let stats = tde.get_stats();
println!("Cached keys: {}/{}", stats.cached_keys, stats.cache_limit);

Algorithms

Algorithm	Speed	Security	Hardware Accel	Use Case
AES-256-GCM	Fast	High	Yes (AES-NI)	Default
ChaCha20-Poly1305	Fast	High	No	CPU w/o AES-NI
AES-256-CTR	Fastest	High*	Yes (AES-NI)	Bulk data

*CTR mode doesn’t provide authentication

Error Handling

match tde.encrypt_table_data("users", data, None).await {
    Ok(encrypted) => { /* success */ }
    Err(TdeError::Encryption(e)) => { /* encryption failed */ }
    Err(TdeError::KeyManager(e)) => { /* key not found */ }
    Err(TdeError::NotInitialized) => { /* TDE not initialized */ }
    Err(e) => { /* other error */ }
}

Environment Variables

# AWS KMS
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...

# HSM
export HSM_PIN=1234

# Key storage
export HELIOSDB_KEY_PATH=/var/lib/heliosdb/keys

YAML Configuration

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

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

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

Testing

Unit Tests

cargo test -p heliosdb-security

Run Example

cargo run --example basic_tde

HSM Tests (requires SoftHSM2)

# Setup
apt-get install softhsm2
softhsm2-util --init-token --slot 0 --label "test" --pin 1234 --so-pin 5678

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

Troubleshooting

”Key not found”

• Check key storage path exists: /var/lib/heliosdb/keys
• Verify permissions: chmod 700 /var/lib/heliosdb/keys
• List keys: key_manager.list_keys(None).await?

”HSM connection failed”

• Check library path: /usr/lib/softhsm/libsofthsm2.so
• Verify HSM is initialized
• Check PIN is correct

”AWS KMS authentication failed”

• Configure credentials: aws configure
• Check IAM permissions: kms:Encrypt, kms:Decrypt
• Verify key ARN is correct

”Performance is slow”

• Enable AES-NI in CPU
• Increase cache size: cache_limit: 10000
• Check cache hit rate: tde.get_stats()

Performance Tips

1. Use AES-256-GCM with AES-NI hardware acceleration
2. Increase cache size for large databases (10,000+)
3. Pre-warm cache on startup by loading common keys
4. Use ChaCha20-Poly1305 if no AES-NI available
5. Monitor cache hit rate and adjust cache size

Security Best Practices

1. Use HSM or Cloud KMS in production (never InMemoryMekProvider)
2. Rotate TEKs annually, MEKs every 2 years
3. Secure key storage path (chmod 600)
4. Use environment variables for sensitive config (HSM PIN, etc.)
5. Enable audit logging (when available)
6. Monitor key access patterns
7. Backup encrypted key envelopes
8. Test disaster recovery procedures

API Reference

TdeSubsystem

pub async fn new(config: TdeConfig) -> Result<Self>
pub async fn encrypt_table_data(&self, table_name: &str, plaintext: &[u8], associated_data: Option<&[u8]>) -> Result<EncryptedBlock>
pub async fn decrypt_table_data(&self, table_name: &str, encrypted_block: &EncryptedBlock) -> Result<Bytes>
pub async fn rotate_table_key(&self, table_name: &str) -> Result<String>
pub fn get_stats(&self) -> TdeStats

KeyManager

pub async fn generate_table_key(&self, table_name: &str, algorithm: Option<EncryptionAlgorithm>) -> Result<String>
pub async fn get_table_key(&self, key_id: &str) -> Result<EncryptionKey>
pub async fn rotate_table_key(&self, key_id: &str) -> Result<String>
pub async fn list_keys(&self, key_type: Option<KeyType>) -> Result<Vec<KeyMetadata>>
pub fn cache_stats(&self) -> CacheStats

TdeEngine

pub fn new(algorithm: EncryptionAlgorithm) -> Self
pub fn encrypt(&self, key: &EncryptionKey, plaintext: &[u8], associated_data: Option<&[u8]>) -> Result<EncryptedBlock>
pub fn decrypt(&self, key: &EncryptionKey, block: &EncryptedBlock) -> Result<Bytes>

Further Reading

• README.md - Comprehensive documentation
• IMPLEMENTATION_SUMMARY.md - Technical details
• examples/basic_tde.rs - Working example
• Security Architecture - Full specification