Encryption (TDE)

GalaxDB supports transparent data encryption (TDE) — every PAX block and WAL record is encrypted with AES-256-GCM before hitting storage. Key management is pluggable via the GALAXDB_KEY_PROVIDER environment variable.

Overview

Encryption is enabled by setting the GALAXDB_KEY_PROVIDER environment variable before starting the server. Without this variable, data is stored unencrypted.

Technical details:

Algorithm: AES-256-GCM (authenticated encryption)
Nonces: 96-bit counter-based (4-byte random prefix + 8-byte atomic counter)
Performance: 680 MB/s encrypt, 709 MB/s decrypt (AES-NI accelerated)
Scope: Every PAX block and WAL record encrypted before write

Note

Encryption is transparent to SQL clients — no changes to queries or connection strings are needed. The key is loaded once at startup and held in memory.

Key Providers

The GALAXDB_KEY_PROVIDER environment variable selects the key provider and its configuration:

bash

GALAXDB_KEY_PROVIDER=<provider>:<config>

Provider	Format	Description
local	local:/path/to/key.bin	32-byte binary key file
env	env:ENV_VAR_NAME	Hex-encoded key from environment variable
command	command:shell command	Delegate to any shell command (AWS CLI, gcloud, etc.)
vault	vault:transit/key-name	HashiCorp Vault Transit engine

Local Key File

Store a 32-byte binary key in a file. Suitable for development and single-server deployments where the key file can be secured via filesystem permissions.

bash

# Generate a 32-byte key
openssl rand -out /etc/galaxdb/key.bin 32
chmod 600 /etc/galaxdb/key.bin

# Start server with local key
GALAXDB_KEY_PROVIDER=local:/etc/galaxdb/key.bin \
galaxdb-server --data-dir /var/lib/galaxdb

Environment Variable

Store the key as a hex-encoded string in an environment variable. Useful for container deployments where secrets are injected as environment variables.

bash

# Generate a hex key
openssl rand -hex 32
# e.g.: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

# Start server with env key
GALAXDB_KEY_PROVIDER=env:GALAXDB_MASTER_KEY \
GALAXDB_MASTER_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
galaxdb-server --data-dir /var/lib/galaxdb

AWS KMS

Use the command: provider to delegate key retrieval to the AWS CLI. The command must output the raw 32-byte key to stdout.

bash

# Encrypt a key with AWS KMS
aws kms encrypt \
  --key-id alias/galaxdb-key \
  --plaintext fileb:///etc/galaxdb/key.bin \
  --output text --query CiphertextBlob > /etc/galaxdb/key.enc

# Start server — AWS CLI decrypts the key at startup
GALAXDB_KEY_PROVIDER="command:aws kms decrypt --ciphertext-blob fileb:///etc/galaxdb/key.enc --output text --query Plaintext | base64 -d" \
galaxdb-server --data-dir /var/lib/galaxdb

Note

The command: provider runs the shell command once at startup and uses the output as the 32-byte key. The command must exit 0 and write exactly 32 bytes to stdout, or the server exits with an error.

HashiCorp Vault

Use the Vault Transit engine for centralized key management. The Vault provider connects to Vault over HTTPS using the VAULT_ADDR and VAULT_TOKEN environment variables.

bash

# Enable Vault Transit engine
vault secrets enable transit
vault write -f transit/keys/galaxdb-prod

# Start server with Vault Transit
VAULT_ADDR=https://vault.example.com:8200 \
VAULT_TOKEN=s.xxxxxxxxxxxxxxxx \
GALAXDB_KEY_PROVIDER=vault:transit/galaxdb-prod \
galaxdb-server --data-dir /var/lib/galaxdb

The Vault provider uses the Transit engine's datakey endpoint to generate a data encryption key, which is wrapped by the Vault master key. The plaintext DEK is held in memory and never written to disk.

Observability

Production Guide