Secret settings

The admin's secret settings (the Mailgun API key, the Expo push access token, the S3 secret key, the license key) are encrypted in the database. A copy of the database, such as a backup, a dump or a leaked table, doesn't give them away, and the admin never shows them: the settings list only says whether each one is there.

Payment keys (STRIPE_*, PAYPAL_*, NETOPIA_*) aren't settings. They live in .env.local, which only the web server's user should be able to read.

The key

Values are sealed with XChaCha20-Poly1305 (libsodium), each one to its setting's name, so a value copied into another setting doesn't open. The key is SETTINGS_KEY, or, while it's empty, a key made from APP_SECRET:

SETTINGS_KEY=   # openssl rand -base64 32

Without SETTINGS_KEY, changing APP_SECRET makes the secret settings unreadable. Set SETTINGS_KEY first and run php bin/console app:settings:encrypt: what the APP_SECRET key sealed is sealed again with the new key, and APP_SECRET can then change freely.

A secret this server can't open counts as not set. The settings list says "Saved with a key this server doesn't have: enter it again", and the log names the setting.

Changing the key

1. Move the current key to SETTINGS_KEY_PREVIOUS and put a new one in SETTINGS_KEY.
2. Run php bin/console app:settings:encrypt. Every secret is sealed again with the new key.
3. Empty SETTINGS_KEY_PREVIOUS.

app:settings:encrypt

The command encrypts secrets that are still in plain text (saved before encryption, or written straight to the database) and seals again those sealed with an older key. It runs with every update (the admin's update page and the Docker entrypoint), never shows a value, and takes --dry-run. With --decrypt it saves the secrets in plain text again, for going back to a release without encryption.