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: Start the Server and Use SQL Normally

export HELIOSDB_JWT_SECRET="$(openssl rand -hex 32)"
heliosdb-lite start --data-dir ./db --config config.toml

CREATE TABLE users (id INT, name TEXT);
INSERT INTO users VALUES (1, 'Alice');

Your data is now encrypted at rest with AES-256-GCM.

---

Testing Encryption

Check the encryption status from any SQL client:

SELECT encryption_enabled, algorithm FROM pg_encryption_status;
--  encryption_enabled | algorithm
-- --------------------+-------------
--  t                  | AES-256-GCM

---

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
• Never commit keys to version control

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

Online key rotation and cloud KMS key sources are planned.

---

Performance

Encryption overhead is minimal:

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

Figures from internal tests (HeliosDB Lite, encrypted vs unencrypted store, representative fixtures); reproduce on your own hardware.

---

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

• Transparent Data Encryption Tutorial
• PostgreSQL SSL/TLS Configuration for encryption in transit

---

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.