Rotating the ThingWorx Flow Encryption Key
Sensitive data including authorizations and workflow actions are encrypted within ThingWorx Flow. You can change the encryption key used to encrypt sensitive data without losing previously encrypted data. The following sections provide information about setting a new encryption key in the following environments:
On-Premise
1. Generate a new key-pair with the key name and secret.
◦ You can set the key name to anything.
◦ The length of the secret must be a multiple of 16. You can use GUID generator to create the secret. The GUID must not contain hyphen (-).
2. The value of the secret parameter is used to decrypt the keyfile-key. To obtain the value of the secret parameter, start Command Prompt as Administrator on the machine where you installed ThingWorx Flow, and run the following commands:
a. pm2 ls
Make note of the value of the ID of any ThingWorx Flow service.
b. pm2 env <id>
, where <id> is the ID of any ThingWorx Flow service. For example: the ID of the flow-api service.
c. Copy the value of the CONFIG_IMAGE variable. This is the value of the secret parameter. This is the value of the secret parameter that you need to provide in step 3.
3. Run the following commands to decrypt the key file:
a. Navigate to the <ThingWorx_Flow_Install_Location>.
b. Run the following commands:
cd <ThingWorx_Flow_Install_Location>\cryptography\tw-security-common-nodejs
Windows: npm link or Linux: sudo npm link
c. Run the following command to decrypt the keyfile-key to a temporary file:
PtcOrchKeyFileTool --secret <CONFIG_IMAGE value> --keyfile-location <ThingWorx_Flow_Install_Location>\misc\keyfile-key --plaintext <ThingWorx_Flow_Install_Location>\cryptography\keys.dec --encrypted <ThingWorx_Flow_Install_Location>\cryptography\keys.enc decrypt
This command creates a new, decrypted keys.dec file under the <ThingWorx_Flow_Install_Location>\cryptography\ folder.
d. Update the keys.dec file to add the new key.
For example: "newkey": "0EE0D33AC67E4389AB2B46123729B875",
e. Make a backup of the <ThingWorx_Flow_Install_Location>\cryptography\keys.enc file.
f. Delete the <ThingWorx_Flow_Install_Location>\cryptography\keys.enc file.
g. Run the following command to create the new encrypted keys.enc file:
PtcOrchKeyFileTool --secret <CONFIG_IMAGE value> --keyfile-location <ThingWorx_Flow_Install_Location>\misc\keyfile-key --plaintext <ThingWorx_Flow_Install_Location>\cryptography\keys.dec --encrypted <ThingWorx_Flow_Install_Location>\cryptography\keys.enc encrypt
h. Delete the decrypted keys.dec file.
4. In the following files, set the value of the activeKeyName property to the new key name to configure the new encryption key:
◦ <ThingWorx_Flow_Install_Location>\modules\engine\config\security-common\config.json
◦ <ThingWorx_Flow_Install_Location>\modules\exchange\config\security-common\config.json
◦ <ThingWorx_Flow_Install_Location>\modules\lookup\config\security-common\config.json
◦ <ThingWorx_Flow_Install_Location>\modules\oauth\config\security-common\config.json
◦ <ThingWorx_Flow_Install_Location>\modules\trigger\config\security-common\config.json
◦ <ThingWorx_Flow_Install_Location>\modules\ux\config\security-common\config.json
For example, for key name, newkey, set the following:
{"
activeKeyName": "newkey"
}
5. Restart ThingWorx Flow services.
Cloud or Virtual Private Cloud
1. Generate a new key-pair with the key name and secret.
◦ You can set the key name to anything.
◦ The length of the secret must be a multiple of 16. You can use GUID generator to create the secret. The GUID must not contain hyphen (-).
2. The ThingWorx Flow deployment includes a key-secret file called <release name>-keys. This key-secret file contains the active encryption key and the old encryption keys in JSON format stored in the oldEncKeys.json. To find the correct key-secret file, execute the following command:
kubectl get secrets
3. Execute the following command to open the secret file for editing:
kubectl edit secret <release name>-keys
The secret file contains the following entries:
◦ ENCRYPTION_KEY:QVNERkdISktMMTIzNDU2Nw==
◦ ACTIVE_ENCRYPTION_KEY_NAME:bXlrZXk=
◦ oldEncKeys.json:e30=
4. Base64 decode the current values of ENCRYPTION_KEY, ACTIVE_ENCRYPTION_KEY_NAME, and oldEncKeys.json. In this example:
◦ For ENCRYPTION_KEY, the value QVNERkdISktMMTIzNDU2Nw== decodes to ASDFGHJKL1234567.
◦ For ACTIVE_ENCRYPTION_KEY_NAME, the value bXlrZXk= decodes to mykey.
◦ For oldEncKeys.json, the value e30= decodes to {}.
5. Base64 encode the new values of ENCRYPTION_KEY,, ACTIVE_ENCRYPTION_KEY_NAME, and oldEncKeys.json. In this example:
◦ For ENCRYPTION_KEY, the value 0EE0D33AC67E4389AB2B46123729B875 encodes to MEVFMEQzM0FDNjdFNDM4OUFCMkI0NjEyMzcyOUI4NzU=.
◦ For ACTIVE_ENCRYPTION_KEY_NAME, the value newkey encodes to bmV3a2V5.
◦ For oldEncKeys.json the old key-pair in JSON format {"mykey":"ASDFGHJKL1234567"} encodes to eyAibXlrZXkiOiAiQVNERkdISktMMTIzNDU2NyJ9
6. Enter the new values in the key-secret file, and then save the file.
◦ ENCRYPTION_KEY:MEVFMEQzM0FDNjdFNDM4OUFCMkI0NjEyMzcyOUI4NzU=
◦ ACTIVE_ENCRYPTION_KEY_NAME:bmV3a2V5
◦ oldEncKeys.json:eyAibXlrZXkiOiAiQVNERkdISktMMTIzNDU2NyJ9
7. Restart all ThingWorx Flow containers.