Back to Overview

Data-at-Rest Encryption

Integration credentials are encrypted at rest with AES-256-GCM. A dedicated DATA_ENCRYPTION_KEY, once existing values are moved onto it and the legacy key is retired, decouples that protection from SECRET_KEY_BASE, so you can rotate your session secret without making every stored credential unreadable.

Luka Breitig, Software Engineer & AI Developer
Luka Breitig

Оновлено 21 жовтня 2026

Why a Dedicated Key

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

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

Setting a dedicated DATA_ENCRYPTION_KEY separates the two secrets. Once the values written earlier are moved onto it and the legacy key is retired (steps 2 and 4 below), you can rotate the session secret whenever you like, and stored credentials keep their own key.

How It Works

Every encrypted value starts with a one-byte version prefix that identifies the key that produced it, so several keys can coexist and data can move from one key to another with no downtime.

Legacy values

Written before you set a dedicated key, encrypted under the SECRET_KEY_BASE-derived key. They still decrypt, because the legacy key stays available for reading.

Current values

Written once DATA_ENCRYPTION_KEY is configured, encrypted under the dedicated key, which is always key 1.

Rotated values

Written under a further key listed in DATA_ENCRYPTION_KEYS once you rotate. The first key in that list writes new values; every other configured key stays readable.

Upgrading changes nothing until you opt in

When DATA_ENCRYPTION_KEY is absent, Tymeslot reads and writes the legacy format exactly as before, so upgrading without changing your configuration is safe. Setting the key switches new writes to the dedicated key; a one-time sweep then migrates your existing values.

1 Enable the Dedicated Key

How you provide the key depends on how you deploy. Once set, it must never change: losing it makes stored credentials unrecoverable.

Cloudron: check first, then set it

First check whether the App Store package has already generated a key for you:

cloudron exec --app tymeslot.yourdomain.com -- ls -l /app/data/data_encryption_key

If the file exists, the package manages the key: do not set one yourself, and go on to the migration in step 2. Otherwise, set one in the app's environment; the app restarts and writes new credentials under it.

cloudron env set --app tymeslot.yourdomain.com DATA_ENCRYPTION_KEY=$(openssl rand -base64 48 | tr -d '\n')

Keep a copy of the value somewhere safe. Existing values still decrypt under the old key, so nothing breaks.

Docker: set it in your .env

Generate a key and add it to the .env next to your Compose file, then run docker compose up -d so the container is recreated with it (a plain restart keeps the old environment):

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

New values are written under the new key straight away. Existing values still decrypt under the old key, so 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 | tr -d '\n' is a good source. A value that is not valid Base64, or is too short, stops Tymeslot at boot with a message naming the variable. So does a SECRET_KEY_BASE shorter than 64 bytes while the legacy key is not retired; replace it with openssl rand -base64 64 | tr -d '\n', which signs every user out once.

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. You can run the sweep as often as you like, and re-run it after an interruption: values already on the new key are left alone.

Cloudron

cloudron exec --app tymeslot.yourdomain.com -- sh -c \
  'SECRET_KEY_BASE="${SECRET_KEY_BASE:-$(cat /app/data/secret_key_base)}" /app/bin/tymeslot eval "Tymeslot.Release.Encryption.reencrypt_credentials()"'

Docker

docker exec tymeslot /app/bin/tymeslot eval \
  "Tymeslot.Release.Encryption.reencrypt_credentials()"

Source install

mix tymeslot.reencrypt_credentials

Each run prints its totals. Re-run until it reports migrated values: 0: every credential is then on the current key.

Values that can't be decrypted are left untouched

Any value that no available key can open (genuinely lost key, corruption) is reported as unrecoverable and left as it is. Those integrations follow the normal reconnection flow, which prompts the user to reconnect. The sweep never deletes or overwrites data it cannot read.

3 Store and Protect the Key

The key now protects every stored credential on its own. Losing it means losing every integration credential at once.

  • Keep one authoritative copy that never changes, plus at least one offline backup of the key 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), at-rest encryption protects you against a leaked database, such as a stray SQL dump, but not against a compromised full backup. To guard against that, inject the key at runtime from a secrets manager that is not part of the backup.

Two rules you must not break

  • Never delete a key that still has values written under it (the environment variable, or on Cloudron, if the package generated your key, the /app/data/data_encryption_key file). Losing it makes those credentials permanently unrecoverable. The only time a key is removed is the last step of a rotation (below), once the key report shows nothing left under it.
  • Do not rotate SECRET_KEY_BASE until the legacy key is retired (below). Until then, some credentials may still depend on the SECRET_KEY_BASE-derived key.

4 Retire the Legacy Key

Once the sweep reports 0, check that nothing is left on the SECRET_KEY_BASE-derived key. The key report lists, per table and column, how many values each key version holds (v0 is the legacy key) and how many no configured key opens (unreadable). Values under a key id that is no longer configured are counted under that id, and the id is named on a line of its own. It never prints a value.

docker exec tymeslot /app/bin/tymeslot eval \
  "Tymeslot.Release.Encryption.key_report()"

When no v0 appears, set LEGACY_KEY_RETIRED=true and restart. From then on SECRET_KEY_BASE plays no part in protecting stored credentials and can be rotated freely.

Retired too early? Nothing is lost

Values still under the legacy key stop opening (their integrations ask to be reconnected) but are never altered, and Tymeslot logs an error at boot naming each affected table and column. Unset the flag, restart, run the sweep and retire the key again, as long as SECRET_KEY_BASE has not changed in the meantime. The exception is the calendar push-channel secrets (Google and Outlook): the daily channel renewal replaces one it cannot read with a fresh one, as it does with every new channel, so push notifications keep working and nothing worth recovering is lost.

Rotating the Key

Rotate when a key may have leaked, or on a schedule. Several keys can be configured at once with DATA_ENCRYPTION_KEYS, an ordered list of id:key entries with ids from 1 to 255. The first entry writes new values; every other entry stays readable, and the sweep moves existing values onto the first. DATA_ENCRYPTION_KEY is always key 1, so it can stay set as it is. Never reuse an id for a different key: the rotation after this one adds key 3.

  1. Back up the database together with the keys in use when it was taken. A backup only opens with the keys it was written under, so keep the old key as long as you keep backups made before the rotation.
  2. Run the key report and note the unreadable counts, so you can tell afterwards that the rotation added none.
  3. Make the new key readable everywhere: set DATA_ENCRYPTION_KEYS="1:<current key>,2:<new key>" and restart. The current key stays first, so nothing is written with the new one yet.
  4. Promote it: set DATA_ENCRYPTION_KEYS="2:<new key>,1:<current key>" and restart. Do this only once you no longer need to roll back to a version older than the one that added DATA_ENCRYPTION_KEYS: such a version reads DATA_ENCRYPTION_KEY alone and cannot open anything written under the new key.
  5. Run the sweep until it reports migrated values: 0, from an instance on the promoted list. An instance still on the previous step writes with the old key, so its sweep would move values back; nothing is lost, but the run has to be repeated.
  6. Verify with the key report: no v1 left, and unreadable no higher than before. That includes oban_jobs.email_links, the links in password reset and verification emails still queued: the sweep leaves them alone and they clear as the emails go out. Wait for them, or accept that a user whose email was still queued requests the link again.
  7. Retire the old key: remove its entry and DATA_ENCRYPTION_KEY, then restart. Removed while the report still shows values under it, those values stop opening until the key is added back; nothing is altered. Tymeslot logs an error at every boot naming the missing key id and how many values each table and column still holds under it, and the integrations affected stop syncing without asking their owners to reconnect, since adding the key back recovers them. On Cloudron, if the package generated the old key, also delete /app/data/data_encryption_key and any DATA_ENCRYPTION_KEY= line in /app/data/.env.

One restart or two

Steps 3 and 4 are separate so that no running instance ever meets a value written under a key it does not have. A single Docker Compose container, or a Cloudron app, is stopped before its replacement starts, so both steps can be one restart straight to the promoted list. Railway keeps the old deployment serving until the new one is healthy, plus any overlap and draining time you configured: there, run them as two redeploys and let the first finish before the second.

Do not rotate by changing the value

Swapping DATA_ENCRYPTION_KEY to a new value in place leaves every credential written under the old one with no key to open it. Add the new key with DATA_ENCRYPTION_KEYS instead, as above.

Frequently Asked Questions

Do I have to set DATA_ENCRYPTION_KEY?

No, but it is recommended. Without it, Tymeslot works as it always has: credentials are encrypted with a key derived from SECRET_KEY_BASE. You only need it if you want to rotate SECRET_KEY_BASE without breaking stored credentials, or want an independent key for defence in depth.

I upgraded and see a warning that DATA_ENCRYPTION_KEY is not set. Is anything broken?

Nothing is broken. The warning is a reminder that your stored credentials are still keyed off SECRET_KEY_BASE, so rotating that secret would make them undecryptable. Set DATA_ENCRYPTION_KEY and run the migration to clear it. On Cloudron, check first whether the package has generated a key (step 1).

What happens if I lose the key?

Every credential written under it becomes permanently unreadable, and each affected integration will prompt the user to reconnect. There is no way to recover them, which is why you need an offline backup of the key, kept apart from your database backups.

How do I know the migration is complete?

Re-run the sweep until it reports migrated values: 0, then check the key report: once no v0 remains, retire the legacy key, and only then rotate SECRET_KEY_BASE.

Is it safe to run the migration while the app is serving traffic?

Yes. The sweep updates each value with a compare-and-swap, so a credential that another process refreshes mid-sweep is never overwritten. Re-running it after an interruption picks up where it stopped, since values already on the new key are skipped.

Verify Your Setup

Confirm each of the following before rotating SECRET_KEY_BASE or retiring a key:
  • 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.
  • The key report shows nothing left on the key you retire. No v0 before setting LEGACY_KEY_RETIRED, and no values under an id before removing it from DATA_ENCRYPTION_KEYS.
  • No key that still holds values has been deleted, and you rotate only by adding a key to DATA_ENCRYPTION_KEYS, removing the old one only once the key report shows nothing under it.

Related Articles

Read reCAPTCHA Bot Protection

reCAPTCHA Bot Protection

Protect Tymeslot's signup and booking forms with Google reCAPTCHA v3. It scores each submission invisibly, so real visitors never solve a puzzle.

Read Self-Host Tymeslot with Docker

Self-Host Tymeslot with Docker

Deploy Tymeslot with Docker Compose on any VPS or home server. Includes reverse proxy setup, file upload volumes, and WebSocket configuration for LiveView.

Read Cloudron Deployment

Cloudron Deployment

Install Tymeslot on Cloudron in minutes. PostgreSQL, SSL certificates, email relay, and automatic updates are all provisioned and managed for you.