Step 8. Encrypt the Configuration File
Security for assets and data is a top priority for companies. For best security practices for your ThingWorx Azure IoT Hub Connector, set up its configuration file to be encrypted, using the Security Management Tool. Encrypting the configuration file provides security for sensitive information, such as network addresses and application keys. This feature is provided starting with v.3.0.0 of the Connector and is compatible with v.8.4.0 and later of the ThingWorx Platform.
This section provides two paths for encrypting the configuration file, one if you are installing the Connector for the first time on a computer and one if you are upgrading an existing Connector. Choose the procedure that fits your installation:
If the encryption.conf file exists
As long as you have set up encryption for the Azure IoT Hub Credentials, the configuration file, encryption.conf, for the Security Management Tool exists. You can use it to encrypt the configuration file for your Connector.
To run the Security Management Tool using the existing encryption.conf file, enter the following command:
./security-common-cli encryption.conf encryptFile /<your-connector-config-path>/connector.conf
/<your-connector-config-path/connector.conf.encrypted
 |
In the command-line example above, a line feed has been added for publishing purposes. If you want to copy/paste the command, first copy/paste it into a text editor and remove the line feed. Then copy it into your shell or Command Prompt window.
|
Next, set the environment variable to point to your configuration file, as explained in
Step 9. Set the Environment Variables for the Azure IoT Hub Connector.
To run the Connector as a non-admin user, which is strongly recommended, you need to run the GrantAzureConnectorPermissions service of the AzureServices Thing provided in the Azure IoT Extension. The Connector may fail to start or run certain services if you do not run this permissions service. For details, refer to
Step 10. Run the Service to Grant Permissions and Visibility to the Connector.
If you need to create the encryption.conf file
The ThingWorx Security Management Tool is a Command Line Interface (CLI) that enables administrators to interact with its underlying security library. This interaction includes creating a configuration file for the tool and then using it to encrypt the configuration file.
You can download the tool from the THINGWORX PLATFORM product family page of the
PTC Software Downloads:
1. Expand the node for your version of ThingWorx Platform. For example, select Release 8.5 for ThingWorx Platform, v.8.5.x.
2. Expand the Security Management Tool node.
3. Expand Most Recent Datecode.
4. Click the Download now button next to the name of the archive.
The process of setting up an encrypted configuration file for the Connector has the following primary steps:
1. Create the configuration file for the encryption library. Refer to the section below,
Creating the
Configuration File for the Encryption Library.
2. Encrypt the configuration file of the Connector, using the Security Management Tool. Refer to the section below,
Encrypting the Configuration
File.
3. Set the environment variables for the Connector. so that it will decrypt the encrypted configuration. Refer to
Step 9. Set the Environment Variables for the Azure IoT Hub Connector .
4. To grant the Connector the required permissions on ThingWorx Platform, refer to
Step 10. Run the Service to Grant Permissions and Visibility to the Connector.
5. Start the Connector with the encrypted configuration file. Refer to
Step 11. Start the Azure IoT Hub Connector.
For more information about the Security Management Tool, refer to the topic,
"Security Management Tool", in the ThingWorx Platform Help Center.
Creating the Configuration File for the Encryption Library
The security-common library of the Security Management Tool requires its own configuration file. To create this file:
1. Navigate to the conf directory of the Connector installatlion,
2. Using a text editor, open the security-sample.conf file and save it as encryption.conf:
3. Edit the file so that it looks something like this:
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 256
keystore {
password-file-path = "/tmp"
password-file-name = "keystore-password"
path = "/tmp"
name = "keystore.jks"
}
}
}
|
|
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_162 or later. If necessary, you can use older versions of Java by updating the Java policy for the key size limit.
|
4. 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 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.
5. Create the password-file-path and path directories specified in the encryption.conf file. In the example above, the directory is /tmp (Linux). On a Windows computer, it would be C:\\tmp.
|
|
You can store the encrypted configuration file anywhere you choose. Just make sure that the encryption configuration file and the environment variables point to the correct path.
|
Alternatively, you can use a vault security library to handle secret management and base encryption requirements. Secret management is a pluggable provider that is managed through a configuration file similar to the following sample-vault.conf provided in the security-common library, in the resources subdirectory:
{
security {
secret-provider = "com.thingworx.security.provider.vault.VaultProvider"
default-encryption-key-length = 256
vault {
address = "http://ip_address:8200"
token-file-path = "/tmp"
token-file-name = "vault-token"
open-timeout = 5
read-timeout = 30
engine = "kv"
application-path = "sample"
}
}
}
Encrypting the Configuration File
Assuming that you have downloaded and extracted the Security Management Tool distribution, follow these steps to encrypt the configuration file:
1. Open a Command Prompt or shell, and navigate to the security-common-cli-v.v.v.v/bin directory.
2. Run the Security Management Tool, as appropriate to your operating system:
◦ Linux — security-common-cli
◦ Windows — security-common-cli.bat
3. When prompted, enter the name of the security configuration file to initialize. Here is a Linux example of the sequence. Note that what you need to enter is in this font:
../security-common-cli-1.0.0.21/bin$ ./security-common-cli
Not initialized, use 'init <config-file>' to initialize
> init [pathTo]encryption.conf
Loading config from file encryption.conf
Secret Provider: com.thingworx.security.provider.keystore.KeyStoreProvider
KeyStore
Path: /tmp/keystore
Password File: /tmp/keystore-password
Keystore Password: <keystore password>
4. While still in the Security Management Tool, encrypt the configuration file of the Connector (in our example azure-iot.conf) using the encryptFile command, as shown below. What you need to type is in this font:
> encryptFile [pathTo]azure-iot.conf [pathTo]azure-iot.conf.encrypted
Created encrypted file azure-iot.conf.encrypted
azure-iot.conf.encrypted is your encrypted configuration file.
5. Verify that the encryption was successful by using the decryptFile command:
> decryptFile [pathTo]azure-iot.conf.encrypted [pathTo]azure-iot.conf.decrypted
Created decrypted file azure-iot.conf.decrypted
The content of the azure-iot.conf.decrypted should match the content of the original azure-iot.conf file.
6. To close the Security Management Tool, type exit at the prompt.
The Connector needs to know where its configuration file is located when it starts up. In addition, it needs to know where the encryption configuration file is located when decrypting credentials for the Azure Hub that are sent from the ThingWorx Platform. Continue to
Step 9. Set the Environment Variables for the Azure IoT Hub Connector .