Sign in Talk to us Start a trial
Start a trial

Design and software studio
Color

The vault and your recovery key

Understand where the data key lives, why the recovery key matters and how to keep both safe.

For
OwnerAdministrator
Hosting
Any hosting
Devices
All devices
Business
All businesses

Checked against Pop Dispatch 0.1.0

Your data is encrypted with a data key. The vault looks after that key and the recovery key that can rebuild it. You will be able to say where your keys are, how to protect them, and what to do if the computer that holds them fails.

Before you start #

You need the owner role and access to the computer that runs Pop Dispatch.

Where the data key lives #

  • Mac apps: the login Keychain.
  • Windows apps: Windows DPAPI, sealed for the signed-in Windows user.
  • Server: the keys folder inside the data folder (readable by its owner only), or the value in PSD_MASTER_KEY_HEX when you set it.

The key never travels on a command line.

The recovery key #

When the server creates a business account in a new data folder, dispatch-server init prints the recovery key once, right after the one-time password. Write it down at that moment, because the server keeps no copy of it.

The recovery key is a printed code in nine groups of four characters, such as XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-CCCC. The last group is a check, so a typing slip is caught before anything happens. You type it in any case and with any spacing.

The vault seals a copy of the data key with the recovery key and saves it as recovery.json. The recovery key itself is shown once and never saved.

Steps to protect your keys #

  1. Print or write the recovery key when it is shown. Keep it away from the computer, for example in a safe.
  2. Protect the data folder with the disk's own encryption (FileVault or BitLocker).
  3. Keep backups on a second disk. See "Backups and restore".
  4. To replace the recovery key, make a new one. The old printed key stops working at once.

If the computer fails #

  1. Install Pop Dispatch on the new computer and choose to restore from the recovery key.
  2. Type the recovery key. A wrong key fails the seal's own check, so it can never produce a wrong data key.
  3. Restore your latest backup. See "Backups and restore".
Technical details
  • Tenant keys are derived from the data key with HKDF-SHA256 and the information pop-street-dispatch|tenant|<id>.
  • recovery.json is version 1: argon2id (64 MiB, 3 passes) makes the sealing key from the recovery key, and AES-256-GCM seals the data key.
  • Choosing "start new" in a folder that already holds .db, .sqlite or .sqlite3 files is refused, because a fresh key would leave those files unreadable for good.
  • Database encryption at rest needs a server built with the sqlcipher option. A server built without it keeps the database file unencrypted and writes a warning to its log at start.
  • The server uses the key to seal webhook signing secrets and to open the database.
  • dispatch-server init saves recovery.json and prints the recovery key once, below the one-time password. A data folder that has a recovery.json already prints no key.
  • The data folder, the keys folder and every file in them are closed to other users (mode 0700 and 0600 on Mac and Linux). On Windows the folder keeps the access rules it inherits, so set them to your own account and the administrators.

If something goes wrong #

  • "A character was mistyped. Check each group against the printed copy.": the last group failed its check. Retype the key.
  • The message that says the recovery key opens a different data set: the key reads correctly but belongs to another folder or an older print. Try the newest printed key.
  • "A recovery key has nine groups of four letters and numbers. Check you typed all of it.": part of the key is missing.
  • You lost the data key and the recovery key: the encrypted files stay closed for good. Keep the recovery key somewhere safe from the first day.