Encryption Quick Start Guide

5-Minute Setup

Step 1: Generate an Encryption Key

# Generate a random 256-bit key
openssl rand -hex 32 > encryption.key

# Protect the key file
chmod 600 encryption.key

Step 2: Set Environment Variable

# Read key from file and set environment variable
export HELIOSDB_ENCRYPTION_KEY=$(cat encryption.key)

Step 3: Configure HeliosDB

Create config.toml:

[encryption]
enabled = true
key_source = { Environment = "HELIOSDB_ENCRYPTION_KEY" }

Step 4: Use Database Normally

use heliosdb_nano::{Config, EmbeddedDatabase};

// Load config with encryption enabled
let config = Config::from_file("config.toml")?;
let db = EmbeddedDatabase::new_with_config("./db", &config)?;

// All data is now automatically encrypted!
db.execute("CREATE TABLE users (id INT, name TEXT)")?;
db.execute("INSERT INTO users VALUES (1, 'Alice')")?;

That’s it! Your data is now encrypted at rest with AES-256-GCM.

Testing Encryption

Verify encryption is working:

let storage = db.storage();

// Check encryption status
if storage.is_encrypted() {
    println!("✓ Encryption enabled");
    println!("  {}", storage.encryption_info().unwrap());
}

Production Deployment

For production, use file-based keys with strict permissions:

# Generate key on secure system
openssl rand -hex 32 > /secure/path/encryption.key

# Set strict permissions
chmod 400 /secure/path/encryption.key
chown heliosdb:heliosdb /secure/path/encryption.key

Update config.toml:

[encryption]
enabled = true
key_source = { File = "/secure/path/encryption.key" }

Key Management Checklist

✅ Before Going Live:

Generate strong random key (256 bits)
Backup key to secure location (separate from data)
Set file permissions (400 or 600)
Test key recovery procedure
Document key rotation schedule
Never commit keys to version control

⚠️ Critical: Without the encryption key, your data is permanently irrecoverable.

Performance

Encryption overhead is minimal:

< 2% for point queries
< 3% for table scans
< 2.5% for inserts/updates

Run benchmarks to verify on your hardware:

cargo bench --bench encryption_benchmark

Troubleshooting

Error: “Environment variable ‘HELIOSDB_ENCRYPTION_KEY’ not found”

Solution:

export HELIOSDB_ENCRYPTION_KEY="your_64_char_hex_key_here"

Error: “Decryption failed”

Cause: Wrong key or corrupted data

Solution: Verify correct key, restore from backup if needed

Error: “Hex key must be 64 characters”

Solution: Generate proper key:

openssl rand -hex 32  # Produces 64 hex characters

Next Steps

Read full documentation: ENCRYPTION.md
Run demo: cargo run --example encryption_demo
Run tests: cargo test --test encryption_tests
Setup key rotation (Phase 2)
Integrate with cloud KMS (Phase 2)

Security Notice

🔒 Encryption protects data at rest (on disk)

It does NOT protect against:

SQL injection (use parameterized queries)
Memory dumps while database is running
Unauthorized access to the server
Network eavesdropping (use TLS for that)

Always use defense in depth: encryption + access controls + network security + monitoring.