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.

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

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.