Rotating ThingWorx Flow Encryption Key
Sensitive data including connections, authorizations, and workflow actions are encrypted within ThingWorx Flow. There may be a need to change the encryption key used to do so without losing the ability to use previously encrypted data. The following steps outline how to set a new encryption key.
On-Premise Deployment Procedure
1. Generate a new key-pair such as key name and secret.
◦ The key name can be anything.
◦ The length of the secret must be a multiple of 16. The simplest method is to use a GUID generator to create the secret.
 |
The GUID must not contain hyphens (-) in it.
|
For this example, the key is newkey and the value is 0EE0D33AC67E4389AB2B46123729B875
2. Decrypt the KeyFile.
a. Navigate to the flow-installer directory, and then copy sec_key from the settings.json file. The key tool uses this later.
b. Navigate to the ThingWorxFlow directory.
c. Link the KeyTool by executing the command that follows:
cd /d C:\ThingWorxFlow\cryptography\tw-security-common-nodejs
npm link
npm link
d. Decrypt KeyFile to a temporary file by executing the commands that follow:
cd /d C:\ThingWorxFlow
C:\ThingWorxFlow> PtcOrchKeyFileTool --secret "<value from sec_key>" --keyfile-location "misc\keyfile-key" --plaintext "keys.dec" --encrypted "cryptography\keys.enc" decrypt
C:\ThingWorxFlow> PtcOrchKeyFileTool --secret "<value from sec_key>" --keyfile-location "misc\keyfile-key" --plaintext "keys.dec" --encrypted "cryptography\keys.enc" decrypt
e. Add a new key to plaintext file such as keys.dec in this example. The connection information for RabbitMQ and Postgres is stored in this file.
f. Encrypt the temporary file to KeyFile by executing the command that follows:
C:\ThingWorxFlow> PtcOrchKeyFileTool --secret "<value from sec_key>" --keyfile-location "misc\keyfile-key" --plaintext"keys.dec"--encrypted "cryptography\keys.enc" encrypt
g. Delete the temporary file keys.dec.
3. For each Flow service, configure the encryption key name and value using the steps that follow:
a. Edit the file deploymentConfig.json.
b. Set the ACTIVE_ENCRYPTION_KEY property to the new key name.
For example, assuming the new key name is "newkey", the deploymentConfig.json should contain the following:
{
"ACTIVE_ENCRYPTION_KEY": "newkey"
}
"ACTIVE_ENCRYPTION_KEY": "newkey"
}
4. Restart the ThingWorx Flow services.
Cloud or Virtual Private Cloud Procedure
1. Generate a new key-pair such as key name and secret.
◦ The key name can be anything.
◦ The length of the secret must be a multiple of 16. The simplest method is to use a GUID generator to create the secret.
|
|
The GUID must not contain an hyphen (-)
|
For this example, the key is newkey and the value is 0EE0D33AC67E4389AB2B46123729B875
2. Find the key secret file. The ThingWorx Flow deployment includes a keys secret (titled <release name>-keys). This secret contains both the active encryption key and old encryption keys in a JSON structure stored in oldEncKeys.json. To find the correct secret, execute the following command:
kubectl get secrets
3. Open the secret file for editing by executing the following command:
kubectl edit secret <release name>-keys
The secret file contains various entries including the following:
◦ ENCRYPTION_KEY:QVNERkdISktMMTIzNDU2Nw==
◦ ACTIVE_ENCRYPTION_KEY_NAME:bXlrZXk=
◦ oldEncKeys.json:e30=
4. Base64 decode the current values of the ENCRYPTION_KEY, ACTIVE_ENCRYPTION_KEY_NAME, and oldEncKeys.json entries. 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 for ENCRYPTION_KEY, ACTIVE_ENCRYPTION_KEY_NAME, and oldEncKeys.json entries. 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 to the secret file, and then save the file.
◦ ENCRYPTION_KEY:MEVFMEQzM0FDNjdFNDM4OUFCMkI0NjEyMzcyOUI4NzU=
◦ ACTIVE_ENCRYPTION_KEY_NAME:bmV3a2V5
◦ oldEncKeys.json:eyAibXlrZXkiOiAiQVNERkdISktMMTIzNDU2NyJ9
7. Restart all the Flow containers.