Data-at-Rest Encryption

🔐 Why a Dedicated Key

Tymeslot encrypts sensitive integration credentials — CalDAV passwords, calendar OAuth tokens, video API keys, Slack and Telegram tokens, webhook secrets — before they are written to the database. By default the encryption key is derived from SECRET_KEY_BASE.

That works, but it welds your data-at-rest protection to your cookie-signing secret: rotating SECRET_KEY_BASE would make every stored credential undecryptable , forcing every user to reconnect every integration.

Setting a dedicated DATA_ENCRYPTION_KEY separates the two secrets. Your session secret becomes freely rotatable, and your at-rest credentials keep their own independent key.

🧩 How It Works

Every encrypted value is self-describing: it carries a one-byte version prefix identifying the key that produced it, so several keys can coexist and data can move from one key to another with no downtime.

1 Enable the Dedicated Key

How you provide the key depends on how you deploy. Once set, it must stay stable forever — losing it makes stored credentials unrecoverable.

Cloudron — automatic

Nothing to do. On the first boot after upgrading, the container generates a key, persists it to /app/data/data_encryption_key (included in Cloudron backups), and starts writing new credentials under it. Then run the migration in step 2.

Docker — set it in your .env

Generate a key and add it to your environment file, then restart:

echo "DATA_ENCRYPTION_KEY=$(openssl rand -base64 48 | tr -d '\n')" >> .env

New values are written under the new key immediately. Existing values keep decrypting under the old key automatically — nothing breaks.

Source / other platforms

Provide DATA_ENCRYPTION_KEY as an environment variable through whatever mechanism your platform uses (Railway variables, a systemd unit, a secrets manager). The value must be Base64 that decodes to at least 32 bytes — openssl rand -base64 48 is a good source.

2 Migrate Existing Credentials

After the dedicated key is configured, existing credentials are still stored under the old key. A one-time sweep rewrites every encrypted value with the new key, so the two secrets become fully independent. The sweep is idempotent and resumable — safe to run repeatedly and to re-run after an interruption.

Cloudron

cloudron exec --app tymeslot.yourdomain.com -- sh -c \
  'export DATA_ENCRYPTION_KEY=$(cat /app/data/data_encryption_key); \
   /app/bin/tymeslot eval "Ecto.Migrator.with_repo(Tymeslot.Repo, fn _ -> IO.inspect(Tymeslot.Security.CredentialReencryption.run(), label: :reencryption) end)"'

Docker

docker exec tymeslot /app/bin/tymeslot eval \\\n  'Ecto.Migrator.with_repo(Tymeslot.Repo, fn _ -> IO.inspect(Tymeslot.Security.CredentialReencryption.run(), label: :reencryption) end)'

Source install

mix tymeslot.reencrypt_credentials

Each run reports per-table counts. Re-run until the reported migrated is 0 — that confirms every credential is on the dedicated key.

3 Store and Protect the Key

The key is now the single thing standing between an attacker and your stored credentials. Treat losing it as equivalent to losing every integration credential at once.

• Keep one authoritative copy that never changes, plus at least one offline backup of the key itself in a password manager or secrets vault — separate from your server backups.
• Never commit it to git, paste it into a ticket or chat, or log it.
• Understand the backup trade-off. If the key lives in the same backup as your database (e.g. Cloudron backs up /app/data, which holds both), then at-rest encryption protects you against a leaked database — a stray SQL dump — but not against a compromised full backup. To defend against backup compromise, inject the key at runtime from a secrets manager that is not part of the database backup.

🔄 Rotating the Key Later

The versioned format is built for rotation, not just this one migration. A future key gets its own version id and coexists with the current one: new writes use the new key, old values keep opening under the previous key, and the same re-encryption sweep walks the data onto the new key. Only once the sweep reports 0 is the previous key retired. Nothing is ever wiped.

❓ Frequently Asked Questions

Verify Your Setup

• The key is configured. The boot warning about DATA_ENCRYPTION_KEY no longer appears in the logs.
• An offline backup of the key exists in a password manager or secrets vault, separate from your database backups.
• The migration reports 0. The re-encryption sweep migrates nothing on its most recent run.
• You have not deleted the key and do not plan to change its value by hand.