Docs Security and admin
Encrypting the company file
A desktop company is one file. Plain, it is a SQLite database anyone with the file can read: a stolen laptop, a shared drive, a backup copied to a stick. Encrypted, nothing readable is ever written to disk: every page is encrypted under the database driver (SQLCipher), the file opens only with its key, and every backup of it is a copy of the encrypted bytes.
It is off by default. For a company whose customer list is private, a clinic or a law office, turn it on the first day.
Turning it on
There is no encryption password to choose. SlowBooks Pro makes the key; you prove who you are and confirm the company. How depends on where the company runs:
- At the SlowBooks Pro window (the desktop app on Windows or a Mac): Settings → Users and security → Company File Encryption → Turn on…, or the Encrypt this company file box on first-run setup. The dialog asks two things and nothing else: the company's name, typed exactly as Settings shows it (the button stays grey, and the line under the box says so, until it matches), and the password you sign in with, not a new one. Then it does the work below.
- On a server (Docker, a cloud host, or Windows started with
--serve-lan), nobody is at a window to unlock the file when the server starts, so the button stays grey until an operator setsCOMPANY_FILE_ENCRYPTION_SECRETin the server's.env(C:\ProgramData\SlowBooksPro\.envon a Windows server; the Docker.envotherwise) and stops and starts the server. Turn on… then asks the company's name only, keys the file from the secret, and makes no recovery key. The Server Edition section below has the detail.
An administrator at the window types the company's name to confirm, and their own password. SlowBooks Pro then:
- makes a recovery key: eight groups of four letters and digits, shown once, with Copy and Save as a text file;
- encrypts the company file under the key that recovery key derives;
- wraps that key for the administrator's password, in a small keyring
file beside the company file (
<company>.db.keyring, which holds nothing secret: each wrapping opens only with its password).
Nobody else should be using the company while the file is rewritten; it takes a few seconds for most books.
Keep the recovery key where the backups are not: a safe, a password manager, a sealed envelope. It opens the file, and every backup of it, on any machine, if every administrator's password is lost, and then lets you set a new administrator password (see A forgotten password below); and anyone holding it can read the books. SlowBooks Pro keeps no copy.
Backups made before you turned it on are still plain, readable by anyone with the file. Settings counts them and says so; delete them once a newer, encrypted backup exists.
Opening the books from then on
The company picker asks for an administrator's sign-in when it opens an encrypted company, or takes the recovery key instead (Use the recovery key instead). Both belong to a file that is already encrypted: a plain company has no recovery key yet, and the picker never asks for one. The administrator who turned encryption on unlocks it at once. Every other administrator unlocks it after their next sign-in inside the books, which wraps the key for their password too; Settings lists who can unlock. Other roles never hold the key: a bookkeeper or an accountant signs in once an administrator has opened the books.
An administrator who is removed, demoted, or whose password an administrator reset, no longer unlocks the file; a reset one does again once they have set a password of their own and signed in.
A forgotten password
The sign-in page's Forgot your password? says what to do for the company in front of you:
- Another administrator can still sign in: ask them to reset it under Settings, Users. They give you a one-time password, and you choose a new one at your next sign-in.
- The file is encrypted: close the company (Choose a different company), open it again, and choose Use the recovery key instead. Once the recovery key has opened it, the sign-in page offers Set a new administrator password: pick the administrator if there are several, and type the new password twice. The company key is wrapped for the new password, so the company list opens the file with it from then on.
- The file is not encrypted (the default): the desktop app offers Set a new administrator password right there. Being at the computer is the proof: anyone who can sign in to that computer can already read a plain company file without the app, so the password keeps a coworker out of the app, not out of the data.
Either reset ends that administrator's other sessions, and the audit log records it as a password reset by the recovery key or at the computer. The reset is made only in the SlowBooks Pro window on the computer that holds the company file: a browser on the network, an API token, Server Edition and a windowless start never get it. On Server Edition, ask another administrator.
The recovery key is not used up by a reset: it still opens the file, and every backup of it. If anyone else may have seen it, make a new one under Settings (below).
A new recovery key
Settings → Users and security → Company File Encryption → New recovery key… re-keys the file in place under a new recovery key, shown once, and retires the old one. The administrator who asked unlocks the file at once; every other administrator after their next sign-in (until then the picker tells them so, and the recovery key or another administrator opens the books). Backups made before the change open with the old recovery key only, so keep it until those backups are gone.
Backups and restores
A backup of an encrypted company is encrypted under the same key; the backups page works as before. Restoring one of this company's own backups needs nothing more. Restoring a backup made under another key (another recovery key, or another install's secret) asks for the recovery key it was made under; the backup file itself is never changed.
Turning it off
Turn off… (an administrator, the company's name typed, and their own password) rewrites the file as plain SQLite and retires the recovery key. Backups made while encryption was on still open with that retired recovery key only, so keep it until those backups are gone.
Server Edition
A server has nobody at the picker, so it unlocks from an operator-set
credential at startup. Set the secret first, then turn encryption on:
put COMPANY_FILE_ENCRYPTION_SECRET in the server's .env
(C:\ProgramData\SlowBooksPro\.env for a Server Edition install, the
place PAYROLL_ENCRYPTION_SECRET lives; the Docker .env otherwise), stop
and start the server, and only then turn encryption on under Settings: the
file is keyed from the secret and no recovery key is made. Turned on before
the secret is set, the company gets a recovery key instead, and the next
server start refuses the file. A file encrypted on a desktop under a
recovery key does not open headless either: open it at the window, turn
encryption off, and turn it on again under the secret.
Companies on PostgreSQL are the database host's job (PostgreSQL's own disk encryption, or the volume it sits on), and the page says so.
What is and is not covered
Covered: the company file on disk, its WAL and sidecars, every backup of it. Not covered: a report or export you saved (a PDF, a CSV, an IIF file) is a plain file where you put it, and the books in a running SlowBooks Pro are readable by whoever is signed in. The technical notes are in Security hardening.