Secrets and the master key

MicroB2B encrypts everything secret it stores with one master key, SECRETS_KEY. This page explains what the key protects, how to keep it safe and how to replace it.

What the key protects

MicroB2B encrypts these values with SECRETS_KEY before it stores them:

the private keys of your certificates;
passwords and header values of partner AS2 profiles and HTTP posters;
the webhook addresses, header values and signing secrets of notifiers;
the authenticator secrets of users;
the client secrets of identity providers.

User passwords, recovery codes, setup links and API tokens are not encrypted but hashed. Nobody can turn them back into the original, with or without the key.

Each encrypted value is tied to where it is sent. A password for a partner opens only for that partner’s address. If someone changes the address directly in the database, the password does not open. So a stored password is never sent to an address it was not entered for.

What it protects against

The key keeps secrets safe when someone gets the database without the key. For example:

a stolen database dump or backup;
a copy of the database on another server;
someone with read access to the database.

It does not help against someone who has both the database and the key, or who controls the MicroB2B server.

Setting the key

Generate the key once:

openssl rand -base64 32

Set it as SECRETS_KEY, or put it in a file and set SECRETS_KEY_FILE to that file. Use one of the two. The key is exactly 32 random bytes, written as base64 or hex. See required settings.

MicroB2B and the microb2b secrets command read the key. MicroB2B does not start without it.

Keeping it safe

Back up the key apart from the database. Store it in a password manager or your company’s safe. If you lose the key, every private key and every stored secret is lost. You would have to upload all private keys and enter all passwords again.

Do not store the key next to the database. A backup that holds both protects nothing.

If you only need a single private key back, and you have the database and the key, you can recover it with OpenSSL alone. See recovering a private key.

Startup check

The database remembers which key it was sealed with. It stores a check value, which reveals nothing about the key. MicroB2B refuses to start when:

SECRETS_KEY is not the key the database expects;
a stored value is sealed with a key that is neither SECRETS_KEY nor in SECRETS_PREVIOUS_KEYS. The log names the id of the missing key.

So a wrong key shows up at once, not later when a message fails. MicroB2B also refuses an unknown variable that starts with SECRETS_, which catches typing errors.

Replacing the key

Replace the key when it may have leaked, or as part of your regular key changes. MicroB2B reads both keys during the change, so nothing stops working.

Generate a new key with openssl rand -base64 32.
Set the new key as SECRETS_KEY. Put the old key in SECRETS_PREVIOUS_KEYS. Restart MicroB2B. From then on it uses the new key for new values and can still read values sealed with the old one.
Run the rekey command with the same key settings and the database settings (DB_TYPE, DB_URL):
```
microb2b secrets rekey
```
It seals every value again with the new key. It reports how many values each old key still has. You can run it while MicroB2B runs.
When the report shows that every value uses the new key, remove the old key from SECRETS_PREVIOUS_KEYS. Restart MicroB2B.

SECRETS_PREVIOUS_KEYS can hold several old keys, separated by commas, spaces or new lines. SECRETS_PREVIOUS_KEYS_FILE names a file that holds them. Old keys only read values. MicroB2B never seals anything with them.

Keep the old key with your backups for as long as you keep backups made before the change. A restore of such a backup needs it.

Replacing the key is not recorded in the audit log, because no setting changes.

Audit log Recovering a private key without MicroB2B