Setting Up an Encrypted Configuration File for an eMessage Connector
To provide greater security for your ThingWorx eMessage Connector you can now set up its configuration file to be encrypted. This feature is provided starting with v.1.2.0 of the Axeda Compatibility Package The installation of the Connector includes the library, security-common. The jar for this library is included in the installation. It provides the backend tool that does the encrypting and decrypting of the configuration file.
A Command Line Interface (CLI) is available to interact with the security library, which includes encrypting the configuration file. For complete information about this CLI, refer to the topic, "Security Management Tool", in the ThingWorx Platform Help Center. This topic explains where to obtain the tool and how to use it. For your convenience, steps specific to the Connector are provided in the sections below. You can download the CLI from the PTC Support Site.
 |
Before you begin, you may want to set up an environment variable that points to the directory where you want to store the encrypted configuration file (emessage.conf.encrypted), the logback.xml configuration file, and the configuration file for the security libraries (encryption.conf). For example, you might create the environment variable, CONFIGURATION_HOME. Refer to When Using an Encrypted Configuration File.
|
The process of setting up an encrypted configuration file for the eMessage 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 eMessage Connector, using the Security Management CLI. Refer to the section below, Encrypting the Configuration File.
3. Set the environment variable for the Connector so that it will decrypt the encrypted configuration. Refer to Setting Environment Variables for an eMessage Connector.
4. Start the Connector with the encrypted configuration file. Refer to Starting the eMessage Connector and Running a Quick Test.
Creating the Configuration File for the Encryption Library
The security-common library requires its own configuration file.
1. Using a text editor, create the following file and save it as encryption.conf:
{
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"
}
}
}
2. 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 CLI 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 CLI, 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.jks
Password File: /tmp/keystore-password
Keystore Password: 3369745037750178919
>
4. While still in the security CLI, encrypt the configuration file of the eMessage Connector (in our example emessage.conf) using the encryptFile command, as shown below. What you need to type is in this font:
> encryptFile [pathTo]emessage.conf [pathTo]emessage.conf.encrypted
Created encrypted file emessage.conf.encrypted
emessage.conf.encrypted is your encrypted configuration file.
5. Verify that the encryption was successful by using the decryptFile command:
> decryptFile [pathTo]emessage.conf.encrypted [pathTo]emessage.conf.decrypted
Created decrypted file emessage.conf.decrypted
The content of the emessage.conf.decrypted should match the content of the original emessage.conf file.
6. To close the CLI, type exit at the prompt.
 |
For best security, when you have completed the encryption of your configuration file, PTC strongly recommends that you remove the Security Management Tool from any production computer that is running the eMessage Connector.
|