tilbudgivern/docs/ENCRYPTED_ENV_README.md

🔐 Encrypted Environment Configuration

Security Implementation Complete

All credentials are now protected with root-only AES-256 encryption. An attacker needs root access to decrypt credentials.

Quick Start

For Development

# Decrypt and start application
sudo ./scripts/start-secure.sh

For Production

# Set up systemd service (one-time setup)
sudo cp scripts/tilbudgivern-secure.service /etc/systemd/system/
sudo systemctl enable tilbudgivern-secure
sudo systemctl start tilbudgivern-secure

Documentation

• Quick Start Guide - Get started in 5 minutes
• Full Security Documentation - Complete security architecture and procedures

How It Works

┌─────────────────────────────────────┐
│  Encryption Key (Root Only)         │
│  /root/.tilbudgivern-secure/        │
│  Permissions: 600 (root:root)       │
└──────────┬──────────────────────────┘
           │
           ├──[Encrypts]──> .env.enc (Safe to commit to git)
           │
           └──[Decrypts]──> .env (Runtime only, auto-cleanup)

Scripts

Script	Purpose
scripts/setup-encrypted-env.sh	Encrypt .env → .env.enc
scripts/decrypt-env.sh	Decrypt .env.enc → .env
scripts/start-secure.sh	Decrypt + Start application
scripts/test-encryption.sh	Test the encryption system

Test the System

# Run the test suite
./scripts/test-encryption.sh

# This will:
# ✓ Create test .env file
# ✓ Encrypt it with root key
# ✓ Decrypt and verify
# ✓ Cleanup

Security Model

✅ What's Protected

• Database passwords
• API keys
• Session secrets
• Authentication credentials

🛡️ How It's Protected

• AES-256-CBC encryption
• PBKDF2 key derivation (100,000 iterations)
• Root-only encryption key (600 permissions)
• Encrypted files safe in git
• Plaintext only exists at runtime

⚠️ Threat Model

• ✅ User account compromise: Credentials safe (can't decrypt)
• ✅ Git repository leak: Only encrypted files exposed
• ✅ File system read access: Encrypted files useless without key
• ❌ Root compromise: System already compromised (defense in depth)

Files in Git

✅ Safe to Commit

• *.env.enc - Encrypted environment files
• .env.example - Template files (no secrets)
• All scripts in scripts/ directory

❌ Never Commit

• .env - Plaintext credentials
• /root/.tilbudgivern-secure/encryption.key - Encryption key

First Time Setup

# 1. Create your .env files
nano backend/.env
nano frontend/.env

# 2. Encrypt them (requires root)
sudo ./scripts/setup-encrypted-env.sh

# 3. Backup encryption key (CRITICAL!)
sudo cp /root/.tilbudgivern-secure/encryption.key /secure/backup/

# 4. Remove plaintext files
rm backend/.env frontend/.env

# 5. Commit encrypted files
git add **/*.env.enc
git commit -m "Add encrypted environment configuration"

Update Credentials

# 1. Decrypt
sudo ./scripts/decrypt-env.sh

# 2. Edit
nano backend/.env

# 3. Re-encrypt
sudo ./scripts/setup-encrypted-env.sh

# 4. Cleanup and commit
sudo ./scripts/decrypt-env.sh --cleanup
git add backend/.env.enc
git commit -m "Update encrypted credentials"

Production Deployment

Using Systemd (Recommended)

The systemd service handles everything automatically:

• Auto-decrypt on startup (requires root)
• Run application as user (alex)
• Auto-cleanup on shutdown

sudo systemctl start tilbudgivern-secure
sudo systemctl status tilbudgivern-secure

Manual Start

# Decrypt and start
sudo ./scripts/start-secure.sh

Backup & Recovery

What to Backup

1. .env.enc files → Git repository (safe)
2. Encryption key → Secure offline backup (CRITICAL!)

Recovery

# 1. Clone repository (gets .env.enc files)
git clone https://github.com/alexpolo1/tilbudgivern.git

# 2. Restore encryption key
sudo mkdir -p /root/.tilbudgivern-secure
sudo cp /backup/encryption.key /root/.tilbudgivern-secure/
sudo chmod 600 /root/.tilbudgivern-secure/encryption.key

# 3. Decrypt and run
sudo ./scripts/decrypt-env.sh

Security Checklist

Before production:

• All .env files encrypted to .env.enc
• Encryption key backed up (not in git!)
• Plaintext .env files removed
• .env.enc files committed to git
• Systemd service configured
• Test encryption/decryption cycle
• Verify key permissions: 600 root:root
• Application runs as non-root user

Troubleshooting

Test the system

./scripts/test-encryption.sh

Common Issues

"Encryption key not found"

sudo ./scripts/setup-encrypted-env.sh  # Generate new key

"Bad decrypt"

• Wrong encryption key → Restore from backup
• Corrupted .env.enc file → Restore from git

"Permission denied"

• Scripts need sudo
• Check: ls -la /root/.tilbudgivern-secure/

Previous Security Issues

This system was implemented after discovering exposed credentials in git history:

✅ Fixed Issues

• Removed all .env files from git history
• Rotated all exposed credentials
• Implemented encrypted environment system
• Root-only encryption key
• Auto-cleanup on shutdown

See commit history for details on git history cleanup.

Support

• Full docs: ENCRYPTED_ENV_SECURITY.md
• Quick start: ENCRYPTED_ENV_QUICKSTART.md
• Test system: ./scripts/test-encryption.sh

---

Security Status: ✅ Production Ready

All credentials are encrypted with root-only keys. System requires root access for encryption/decryption, ensuring credentials are protected even if user account is compromised.