Step 7. Set Up Encryption for Azure IoT Hub Credentials
For the Azure IoT Hub Connector to be able to communicate with the Azure IoT Hub, you must set up the Connector and ThingWorx Platform to support encryption/decryption of the Azure Hub credentials. The Azure IoT Hub Connector encryption key must be added to the keystore of your ThingWorx Platform. It is recommended that the shared key is different from the internal Platform key.
To set up encryption/decryption of Azure IoT Hub credentials, follow these steps:
1. IIf you previously started your ThingWorx Platform, skip to the next step. If you have not started it yet, start the ThingWorx Platform to automatically generate a keystore file and a keystore-password file. These files are typically generated in the directory, ThingworxStorage.
2. If you have not already done so, download the Security Management Tool from the
Software Downloads page for the ThingWorx Platform on the PTC Support site.
 |
The Security Management Tool requires JDK1.8_u161 or later to use an encryption key length of 256 bits. JDK 1.8_u141 is the minimum version required for the tool; it supports an encryption key length of 128 bits.
Starting with v.8.5.0 of the ThingWorx Platform and v.3.0.0 of the ThingWorx Azure IoT Hub Connector, the keystore files use the .pfx format instead of .jks.
|
3. Once you have extracted the Security Management Tool, create a default encryption.conf file that points to the keystore and keystore-password files on your ThingWorx Platform:
a. Locate the security-sample.conf file in the conf directory of the Connector installation.
b. Open the file in your favorite text editor.
c. To use this sample file as a starting point, save it as encryption.conf, and edit it so it resembles this example when running on Linux:
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 256
keystore {
password-file-path = "/ThingworxPlatform"
password-file-name = "keystore-password"
path = "/ThingworxStorage"
name = "keystore"
}
}
}
The following example shows the paths as they need to be when running on Windows:
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 256
keystore {
password-file-path = "C:\ThingworxPlatform"
password-file-name = "keystore-password"
path = "C:\ThingworxStorage"
name = "keystore"
}
}
}
4. Generate a new encryption key for the Connector. The following example of the command uses the default name, azure.connector.key, for the encryption key:
./security-common-cli encryption.conf generate-key azure.connector.key
|
|
Use the default name. Otherwise, you will have to add the property, encryption-key-name and the name you used to the configuration file for the Connector.
|
5. Retrieve the value of the encryption key. The following example of the command uses the default name, azure.connector.key, for the encryption key:
./security-common-cli encryption.conf get azure.connector.key
The output contains the encryption key value, which looks something like this:
pE8/LVwbQY74hDrXhBeP5w==
6. In a secure location, save the output value of the encryption key. Next, you will add it to the keystore of the Azure IoT Hub Connector. Once you have done that, you will delete the output value.
To support decryption of the Azure IoT Hub credentials, the encryption key generated in the procedure above must be added to the keystore of the Azure IoT Hub Connector. Assuming that you have the Security Management Tool, follow these steps:
1. Create a default encryption.conf file that points to the locations where you want the keystore and keystore-password files for the Azure IoT Hub Connector to be created. For example:
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 256
keystore {
password-file-path = "."
password-file-name = "keystore-password"
path = "."
name = "keystore"
}
}
}
 |
The default setting for default-encryption-key-length is 128, but as shown above, you can use 256–bit encryption. However, you must be using Java 1.8.0_161 or higher. If necessary, you can use older versions of Java by installing the Java Cryptography Extension (JCE) "Unlimited Strength Jurisdiction Policy Files" to the JAVA_HOME directory for the Connector
|
2. For the keystore.name property, what you enter depends on whether you are upgrading your Connector or installing a new Connector:
◦ New Connector — Do NOT use an extension. Starting with ThingWorx Platform 8.5, the Security Management Tool now uses PCKS12 keystore type.
◦ Upgrading — Leave the keystore file name with the .jks extension. Otherwise a new keystore is created as named but the old keys are not migrated. If you leave the extension as .jks, a new keystore is created and all the old keys are migrated.
3. Using the Security Management Tool, add the encryption key value that you saved in the ThingWorx Platform setup. For example:
./security-common-cli encryption.conf set azure.connector.key pE8/LVwbQY74hDrXhBeP5w==
At this point, the encryption key for the Azure IoT Hub should exist with an identical value in both the ThingWorx Platform keystore and the Azure IoT Hub Connector keystore.
4. For best security practices, delete the output value for the encryption key from the location where you saved it.