Setting Up an Encrypted Configuration File
To provide greater security for your ThingWorx AlwaysOn Connection Server, you can now set up its configuration file to be encrypted. This feature is provided starting with v.8.4.0 of the ThingWorx Platform and the Connection Server. The installation of the Connection Server includes the library, security-common. The jar for this library is included in the Connection Server 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, see 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 Connection Server 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 (cxserver.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.
|
The process of setting up an encrypted configuration file for the Connection Server has the following primary steps:
1. Create the configuration file for the encryption library. See the section below, Creating the Configuration
File for the Encryption Library.
2. Encrypt the configuration file of the Connection Server, using the Security Management CLI. See the section below, Encrypting the Configuration
File.
3. Set the environment variables for the Connection Server so that it will decrypt the encrypted configuration. See Setting
the Environment Variable When Using an Encrypted Configuration.
4. Start the Connection Server with the encrypted configuration file. See Starting the Connection Server 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 Connection Server (in our example cxserver.conf) using the encryptFile command, as shown below. What you need to type is in this font:
> encryptFile [pathTo]cxserver.conf [pathTo]cxserver.conf.encrypted
Created encrypted file cxserver.conf.encrypted
cxserver.conf.encrypted is your encrypted configuration file.
5. Verify that the encryption was successful by using the decryptFile command:
> decryptFile [pathTo]cxserver.conf.encrypted [pathTo]cxserver.conf.decrypted
Created decrypted file cxserver.conf.decrypted
The content of the cxserver.conf.decrypted should match the content of the original cxserver.conf file.
6. To close the CLI, type exit at the prompt.