---
title: "Encryption Quick Start Guide"
---

# Encryption Quick Start Guide

## 5-Minute Setup

### Step 1: Generate an Encryption Key

```bash
# 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

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

### Step 3: Configure HeliosDB

Create `config.toml`:

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

### Step 4: Start the Server and Use SQL Normally

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

```sql
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:

```sql
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:

```bash
# 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`:

```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:
```bash
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:
```bash
openssl rand -hex 32  # Produces 64 hex characters
```

---

## Next Steps

- [Transparent Data Encryption Tutorial](/docs/lite/guides/tutorials/encryption_tutorial/)
- [PostgreSQL SSL/TLS Configuration](/docs/lite/guides/postgresql_ssl_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.