Encryption

DATA_KEY is required — Klokk does not start without it. It encrypts the database and protects the key of the especially sensitive details: Klokk also seals MFA secrets, comments on absences, push and webhook secrets and special working-time protection one by one (AES-256-GCM), with a random key that lies in the database only encrypted with DATA_KEY.

Depending on the database:

• SQLite: Klokk encrypts the whole database file including its journal (SQLite3 Multiple Ciphers, ChaCha20-Poly1305). An existing database is converted at the first start with DATA_KEY: Klokk writes an encrypted copy, checks it against the original (integrity, rows per table) and only then swaps the files. No other process may have the database open meanwhile. If anything fails, the original stays as it was, Klokk keeps running unencrypted, tells super admins why and tries again at the next start. Copies of the file (backups) are encrypted from then on as well.
• PostgreSQL: Klokk also seals all free texts — activity notes, descriptions of project time, reasons and comments of correction and swap requests, notes on shifts, vacation and time account bookings, and the webhook logs; existing texts at the first start. Names, e-mail addresses and working times stay readable, as Klokk searches and calculates with them. Klokk cannot encrypt the database server’s files: encrypt the storage for that (e.g. LUKS, ZFS) and secure the connection with TLS (sslmode=verify-full).
• SESSION_SECRET protects no data: it only signs sign-in cookies and calendar links and can be changed at any time (calendar subscriptions are then set up again).

Caution

Keep DATA_KEY safe — without it the data is lost If DATA_KEY is missing or has another value, Klokk does not start: the database cannot be opened any more, not even from a backup. Keep the value apart from the backups, for example in a password manager. DATA_KEY cannot be removed again. After an existing SQLite database has been converted, remnants of the unencrypted file may stay on the storage until they are overwritten; older backups stay unencrypted. Where that must be ruled out, encrypt the storage as well.