Transparent Data Encryption (TDE)

HeliosDB-Lite provides Transparent Data Encryption (TDE) using AES-256-GCM and an optional Zero-Knowledge Encryption (ZKE) mode where keys never leave the client. This tutorial covers enabling TDE, key management, rotation, and monitoring.

Prerequisites

HeliosDB-Lite v3.5 or later
Access to configuration files or environment variables

How TDE Works

When TDE is enabled, HeliosDB encrypts all data values before writing them to storage and decrypts them transparently on read. The encryption is invisible to application SQL — queries, inserts, and updates work exactly the same way.

Algorithm: AES-256-GCM (authenticated encryption with associated data)
Nonce: Each encryption operation uses a random 96-bit nonce, prepended to the ciphertext
Key derivation: PBKDF2 with 100,000 iterations (NIST SP 800-132 compliant)

Step 1 — Set an Encryption Key

The encryption key can be provided via an environment variable, a file, or a KMS provider.

Option A: Environment Variable

# Generate a 256-bit hex key (64 hex characters)
export HELIOSDB_ENCRYPTION_KEY=$(openssl rand -hex 32)

Option B: Key File

openssl rand -hex 32 > /etc/heliosdb/encryption.key
chmod 600 /etc/heliosdb/encryption.key

Option C: KMS (AWS, GCP, Azure)

Configure in heliosdb.toml:

[encryption]
enabled = true
key_source = { Kms = { provider = "aws", key_id = "arn:aws:kms:us-east-1:123:key/abc-123" } }

Step 2 — Enable TDE in Configuration

Edit heliosdb.toml:

[encryption]
enabled = true
algorithm = "Aes256Gcm"
key_source = { Environment = "HELIOSDB_ENCRYPTION_KEY" }
rotation_interval_days = 90

Or using a key file:

[encryption]
enabled = true
key_source = { File = "/etc/heliosdb/encryption.key" }

Step 3 — Start the Database

Start HeliosDB with the encryption key available:

HELIOSDB_ENCRYPTION_KEY=<your-hex-key> heliosdb-lite --config heliosdb.toml

All subsequent writes will be encrypted. Reads will be decrypted transparently.

Step 4 — Verify Encryption is Active

Query the system configuration view:

SELECT * FROM helios_config WHERE section = 'encryption';

The output confirms encryption is active and shows the algorithm in use.

Step 5 — Key Rotation

Rotate the encryption key without downtime using ALTER SYSTEM:

ALTER SYSTEM ROTATE ENCRYPTION KEY;

This generates a new key version. Existing data encrypted with the previous key is re-encrypted on the next compaction or vacuum cycle. Both old and new keys are valid during the transition.

Step 6 — Monitor Key Versions

The helios_encryption_keys system view shows all key versions and their status:

SELECT * FROM helios_encryption_keys;

 key_version                          | active | created_at
--------------------------------------+--------+---------------------------
 a1b2c3d4-e5f6-7890-abcd-ef1234567890 | true   | 2025-03-26T10:00:00Z
 f9e8d7c6-b5a4-3210-fedc-ba0987654321 | false  | 2025-01-15T08:30:00Z

The active column indicates which key version is currently used for new writes.

Step 7 — Zero-Knowledge Encryption (ZKE)

ZKE is an advanced mode where encryption keys never leave the client. The server only ever sees encrypted data and cannot decrypt it without the client providing the key on each request.

ZKE Modes

Mode	Description
`full`	Client encrypts all data before transmission
`hybrid`	Metadata unencrypted, row data encrypted
`per_request`	Key provided per-request for server-side operations

Enable ZKE

[encryption.zke]
enabled = true
mode = "per_request"
require_key_hash = true
replay_protection = true
nonce_window_secs = 300

With ZKE in per_request mode, each API request includes a key header:

POST /api/v1/query
X-Encryption-Key: <base64-encoded-key>
X-Key-Hash: <sha256-of-key>
X-Request-Nonce: <unique-nonce>

The server uses the provided key for that request only and never stores it.

Step 8 — Cryptographic Providers

HeliosDB supports two cryptographic backends:

Provider	Feature Flag	Details
ring + BLAKE3	`ring-crypto`	Default, high performance
AWS-LC (FIPS)	`fips`	FIPS 140-3 compliant (#4816)

Build with FIPS mode:

cargo build --features fips --no-default-features

Tips and Troubleshooting

Key loss: If you lose the encryption key, the data cannot be recovered. Always back up your key in a secure location (KMS, HSM, or encrypted vault).
Performance impact: AES-256-GCM with hardware acceleration (AES-NI) adds roughly 5-10% overhead. On CPUs without AES-NI, overhead can be higher.
Existing data: Enabling TDE on an existing database encrypts new writes immediately. Existing unencrypted data is encrypted during the next compaction or by running VACUUM.
PBKDF2 iterations: HeliosDB uses 100,000 PBKDF2 iterations for key derivation, meeting NIST SP 800-132 recommendations. This is intentionally slow to resist brute-force attacks.
Rotation interval: The default rotation interval is 90 days. Adjust rotation_interval_days to match your compliance requirements.
Backup encryption: Database backups include encrypted data. You need the same encryption key (or a valid historical key version) to restore from backup.