Rotate the encryption key

Platform 6.6.0+

Use the key rotation utility to replace the encryption key that Itential Platform uses to protect secrets. The utility decrypts the encrypted values in your database with the old key and re-encrypts them with a new key.

To migrate encrypted secrets from an earlier Platform version, instead use the key migration utility.

Before you begin

Before you rotate the key, complete the following tasks:

Back up your MongoDB database. The utility modifies the database directly, so Itential recommends a backup before every rotation. If the rotation is interrupted, restore the database from your backup and run the utility again. For instructions, see Back up MongoDB data.
Gather the following items:
- The current encryption key.
- The new encryption key.

Rotate the key

In a high availability environment, stop all Platform instances before you rotate the key. Run the utility once, and update the configuration for every Platform instance before you start any of them.

Stop Platform

The utility can’t run while Platform is running. For more information, see Start, stop, and restart Platform.

sudo systemctl stop itential-platform

Go to the server directory

cd /opt/itential/platform/server

Run the key rotation utility

Run the command that matches how you configure Platform. Replace $OLD_KEY with your current encryption key and $NEW_KEY with your new encryption key.

If you use a platform.properties file, run the following command:

npm run key:rotate -- \
  --config-file /etc/itential/platform.properties \
  --old-encryption-key "$OLD_KEY" \
  --new-encryption-key "$NEW_KEY"

If environment variables fully define your configuration, run the following command. Use --only-env in place of --config-file.
```
npm run key:rotate -- \
  --only-env \
  --old-encryption-key "$OLD_KEY" \
  --new-encryption-key "$NEW_KEY"
```

Rotate custom collections (optional)

If you have custom collections that contain encrypted values, add them with --extra-collections. Repeat the option for each collection.

npm run key:rotate -- \
  --config-file /etc/itential/platform.properties \
  --old-encryption-key "$OLD_KEY" \
  --new-encryption-key "$NEW_KEY" \
  --extra-collections custom-collection-1 \
  --extra-collections custom-collection-2

Update encrypted values in your configuration

If your configuration contains encrypted values, the utility outputs their rotated counterparts. In your configuration file or environment variables, replace each existing value with its new value.

Start Platform

Don’t start Platform instances until you update every encrypted value in your configuration with its rotated counterpart.

Configure Platform to use the new encryption key, and then start it.

sudo systemctl start itential-platform

Command options

The key rotation utility supports the following options:

Option	Alias	Description
`--old-encryption-key`	`-o`	The current encryption key.
`--new-encryption-key`	`-n`	The new encryption key.
`--config-file`	`-f`	The path to the Platform configuration file.
`--only-env`		Reads configuration only from environment variables. Use this option in place of `--config-file` when environment variables completely define your configuration.
`--extra-collections`	`-c`	A custom collection to rotate in addition to the default collections. Repeat the option for each collection.
`--only-collections`	`-q`	Rotates only the specified collections. For more information, see Choose which collections to rotate.

Choose which collections to rotate

By default, the utility rotates the following collections:

service_configs
oauth_clients
accounts
iap_profiles
itential_provider_profiles
itential_agent_sessions

To add collections to this list, use --extra-collections.

To rotate a specific set of collections instead, use --only-collections. The utility then rotates only the collections that you specify. It ignores the default collections and any collections that you pass with --extra-collections.