Encryption

Supascale uses industry-standard encryption to protect sensitive data at rest. This guide explains what's encrypted, how encryption works, and best practices for managing encryption keys.

What's Encrypted

Supascale automatically encrypts sensitive data including:

Encryption Algorithm

Supascale uses AES-256 (Advanced Encryption Standard with 256-bit keys) for symmetric encryption. This is the same standard used by:

• US Government for classified information
• Financial institutions
• Major cloud providers

AES-256 is considered secure against brute-force attacks - there are more possible keys than atoms in the observable universe.

Encryption Key

All encryption uses a master key configured via the DB_ENCRYPTION_KEY environment variable.

Key Requirements

• Minimum length: 32 characters
• Recommended: 64 hexadecimal characters (256 bits)

Generating a Key

Generate a secure encryption key using OpenSSL:

openssl rand -hex 32

This produces a 64-character hexadecimal string.

Configuring the Key

Set the encryption key in your .env file:

DB_ENCRYPTION_KEY=your_64_character_hex_key_here

Important: Keep this key secure. If lost, encrypted data cannot be recovered.

How Encryption Works

Encrypting Data

When sensitive data is stored:

1. Plain text data is received
2. AES-256 encryption is applied using the master key
3. Encrypted data is stored in the database
4. Original plain text is discarded

Decrypting Data

When encrypted data is accessed:

1. Encrypted data is retrieved from storage
2. AES-256 decryption is applied using the master key
3. Plain text is returned to the application
4. Plain text is used only in memory, never persisted

Masking in UI

Even after decryption, sensitive data is masked in the user interface:

• OAuth secrets show only first/last 4 characters: abc1...xyz9
• API keys are never shown after creation (only hashed)
• Passwords are always masked: ••••••••

SSL Private Key Encryption

SSL private keys receive special handling:

1. When a certificate is obtained/uploaded, the private key is encrypted
2. Stored as privkey.pem.enc alongside the certificate
3. Decrypted only when needed for HTTPS configuration
4. Original unencrypted key is never stored

Best Practices

Key Management

1. Generate a strong key: Use the full 256-bit key space
2. Never commit the key: Keep it out of version control
3. Limit access: Only administrators should have access to the key
4. Backup securely: Store a backup in a secure location (e.g., password manager, hardware security module)

Key Rotation

While Supascale doesn't currently support automatic key rotation, you can manually rotate:

1. Export all encrypted data
2. Generate a new encryption key
3. Update the DB_ENCRYPTION_KEY environment variable
4. Re-encrypt all data with the new key

Disaster Recovery

1. Document the key location: Know where the key is stored
2. Test recovery: Verify you can access the key if needed
3. Maintain backups: Both encrypted data and the key (separately)

Hashing vs Encryption

Supascale uses both encryption and hashing:

API keys are hashed rather than encrypted because:

• The original key is shown once at creation
• We only need to verify keys, not retrieve them
• One-way hashing is more secure for authentication tokens

Security Considerations

Defense in Depth

Encryption is one layer of security. Also implement:

• Network security (firewalls, VPNs)
• Access control (authentication, authorization)
• Monitoring (logging, alerting)
• Physical security (server access)

Limitations

Encryption protects data at rest but:

• Data is decrypted in memory when used
• Anyone with the encryption key can decrypt data
• Encryption doesn't prevent authorized misuse