Token secret rotation

All encrypted information in Informer, such as Datasource connection passwords, is encrypted with a master password called the token secret. If the token secret were exposed, anything Informer encrypted with it could be decrypted. Token secret rotation lets cluster administrators change the token secret and automatically re-encrypt all stored secrets, instead of updating every encrypted password by hand.

Back up first

Use token secret rotation as part of a breach or disaster-recovery procedure, and back up your PostgreSQL database first. See Backups and restores (Windows).

Move the token secret into a file

Any token secret currently defined in a server's config.json (or passed via the command line, pm2 config, or service arguments) must be removed and moved into a file named default.crypt in the configured etc directory. By default, etc is a folder named etc in the directory Informer runs from. For Docker, it can be a mounted volume at /informer/etc.

Where etc is on a server built by Informer Setup

Informer Setup keeps the application separate from your data and points Informer's etc directory at the data directory, so default.crypt is at etc\default.crypt under the data directory, for example C:\Entrinsik\Informer5 Server\data\etc\default.crypt. On a server built by the older console installer it is in the installation's etc folder or at its root. Migration carries the key to the new location, including a token secret still in config.json: it is written to default.crypt and left out of the migrated config.json. Migration stops while a new.crypt exists: finish the rotation, including the cleanup step below, first.

Both methods are supported as of 5.10

As of Informer 5.10, both ways of defining a token secret (the config variable and default.crypt) are supported. Future releases may deprecate the config-variable approach to make disaster recovery smoother.

For example, given a config.json like this:

{
  "name": "Informer5",
  "tokenSecret": "ThisIsMyTokenSecretThereAreManyLikeItButThisOneIsMine",
  "http": 80,
  "db": {
    "database": "postgres-example-database",
    "host": "postgres-example-server",
    "user": "postgres-example-user",
    "password": "postgres-example-password",
    "port": 5432
  }
}

First, remove the tokenSecret property:

{
  "name": "Informer5",
  "http": 80,
  "db": {
    "database": "postgres-example-database",
    "host": "postgres-example-server",
    "user": "postgres-example-user",
    "password": "postgres-example-password",
    "port": 5432
  }
}

Then create default.crypt in the etc directory containing just the token secret:

ThisIsMyTokenSecretThereAreManyLikeItButThisOneIsMine

The file must hold exactly the token secret

Informer reads default.crypt as it is, without trimming it. A line break or space after the secret makes it a different key, and Informer refuses to start. Save the file with nothing after the last character of the secret.

After restarting, Informer functions exactly as before.

Rotate to a new token secret

To rotate the old secret for a new one, create another file in the same etc directory called new.crypt containing the new token secret. When Informer starts with both files present, it re-encrypts all encrypted values with the new secret. Once Informer is running, test a Datasource connection to confirm the encrypted values migrated successfully.

As a final cleanup step, move the contents of new.crypt into default.crypt, delete new.crypt, and restart Informer. Informer is then running normally with its token secret in default.crypt.

Complete the cleanup before rotating again

The cleanup step must be done before any subsequent token secret rotation.