Skip to content

Encrypt Checkbox secrets

A one-off housekeeping operation: encrypt the cashier passwords, PIN codes and till license keys that older databases kept in clear text.

Where to find it: Modules → Checkbox → Maintenances → Encrypt Checkbox secrets

A worked example

Encrypt Checkbox secrets

The window is an explanation and a single working button. "Scheduled" is disabled on purpose: the operation runs once, so there is nothing to automate.

What it does, and why it is safe

The service walks the Checkbox accounts of every company in the database at once, not just the current one, and encrypts three fields: the cashier's password and PIN code and the till's license key. Values that are already encrypted or blank are skipped, so running it again changes nothing — the defining property of this kind of migration.

Along the way, the search fingerprint of every cashier and till row is rebuilt — without the secrets. This happens even when a secret is already encrypted: in rows saved on an older version the fingerprint was built from every field, so the password and PIN code could have stayed in it in plain text.

The interface does not show the secrets themselves either before or after the run: the fields are empty in the card, and typing a new value means replacing the stored one.

After the run the service shows a summary on screen: how many rows were encrypted, in how many an open secret was found in the search text and removed, and in how many the search text was rebuilt without private fields. A row that was changed while the service was running is left alone and reported in a summary line with a warning triangle — run the operation again.

Encryption key and failures

  • The encryption key is part of the server configuration; it is not in the database. If the key is changed or lost, or the database is moved to a server with a different key, the stored secrets can no longer be decrypted: Checkbox will reject the cashier password, and the secrets have to be entered in the card again.
  • No key on the server — the service stops at the first plain-text secret with the message "The secret could not be encrypted on the server. Ask the administrator to check the encryption key"; plain-text values stay as they were.
  • There is no reverse operation: secrets are never turned back into plain text. The server decrypts only the cashier password, at the moment it logs in to Checkbox during the sales import; no operation reads the PIN code or the cashbox license key.
  • Rows are written one by one, not in a single transaction: if the service stops halfway, what is done stays done, and a repeat run finishes the rest.

When to run it

  • A long-running database — once, after the update that introduced encryption.
  • A fresh database — not needed: secrets are encrypted on save from the start.
  • Not sure — run it: an extra pass is harmless.

Where to look next