78 lines
2.9 KiB
Markdown
78 lines
2.9 KiB
Markdown
# Encryption key rotation (production)
|
|
|
|
This runbook describes how to rotate `ENCRYPTION_KEY` without data loss. The application encrypts user PII, TOTP secrets, hot-wallet keys, and other sensitive columns at rest.
|
|
|
|
## Prerequisites
|
|
|
|
- Maintenance window (API can stay up; rotation is I/O heavy on large tables).
|
|
- Current and new 32-byte keys (base64 or hex per your `ENCRYPTION_KEY` format).
|
|
- Database backup before starting.
|
|
- Shell access to the API host or a job runner with `DATABASE_URL` and keys.
|
|
|
|
## Settings
|
|
|
|
| Variable | Purpose |
|
|
|----------|---------|
|
|
| `ENCRYPTION_KEY` | Active encryption key (after rotation: the **new** key) |
|
|
| `ENCRYPTION_KEY_PREVIOUS` | Previous key; required during rotation so `decrypt()` can read legacy ciphertext |
|
|
| `ENCRYPTION_KEY_ROTATION_REMIND_DAYS` | Optional; days before daily reminder (default `90`) |
|
|
|
|
The API records `encryption_key_rotated_at` in `system_settings` when rotation completes successfully.
|
|
|
|
## Rotation steps
|
|
|
|
1. **Generate a new key** (example):
|
|
|
|
```bash
|
|
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
|
|
```
|
|
|
|
2. **Set environment** on the rotation job (not production API yet):
|
|
|
|
```bash
|
|
export ENCRYPTION_KEY_PREVIOUS="<current-key>"
|
|
export ENCRYPTION_KEY="<new-key>"
|
|
export DATABASE_URL="<production-database-url>"
|
|
```
|
|
|
|
3. **Run the rotation script** from `backend/`:
|
|
|
|
```bash
|
|
npm run rotate-encryption-key
|
|
```
|
|
|
|
This re-encrypts all managed columns and updates `encryption_key_rotated_at`.
|
|
|
|
4. **Deploy the new `ENCRYPTION_KEY`** to all API/worker processes. Remove `ENCRYPTION_KEY_PREVIOUS` from runtime env after verification.
|
|
|
|
5. **Verify**:
|
|
- Login, 2FA, withdrawals, and admin user detail (email decrypt).
|
|
- Check logs for decrypt errors.
|
|
- Confirm `encryption_key_rotated_at` in `system_settings`.
|
|
|
|
## Scheduled reminder
|
|
|
|
On boot, the API runs a daily check (`encryptionRotationReminderService`). If the key is older than `ENCRYPTION_KEY_ROTATION_REMIND_DAYS`, it logs a warning and creates an admin notification.
|
|
|
|
Rotation itself is **manual** (script above). Do not auto-rotate keys without updating deployment secrets in the same change window.
|
|
|
|
## Cron example (optional)
|
|
|
|
Run rotation from a secure CI job or cron **only** when keys are pre-staged:
|
|
|
|
```cron
|
|
# Example: quarterly rotation at 03:00 UTC on the 1st — adjust to your policy
|
|
0 3 1 */3 * cd /opt/games-app/backend && ENCRYPTION_KEY_PREVIOUS=... ENCRYPTION_KEY=... npm run rotate-encryption-key >> /var/log/encryption-rotation.log 2>&1
|
|
```
|
|
|
|
After the job succeeds, update the orchestrator secrets and redeploy before removing `ENCRYPTION_KEY_PREVIOUS`.
|
|
|
|
## Rollback
|
|
|
|
If rotation fails mid-run:
|
|
|
|
1. Stop the script.
|
|
2. Restore `ENCRYPTION_KEY` to the **previous** value across all services.
|
|
3. Restore database from backup if partial writes occurred.
|
|
4. Investigate logs from `rotate-encryption-key` before retrying.
|