ThingWorx Model Definition in Composer > Security > Security Management Tool
Security Management Tool
The Security Management Tool is a way to manage secure information used by the ThingWorx software. The tool can encrypt any key value from the configuration files for these products, such as database and licensing passwords. You can use this tool with any ThingWorx application and it is supported with products such as the ThingWorx Platform, Connection Server, ThingWorx Azure IoT Hub Connector v.3.0.0, ThingWorx Edge MicroServer (EMS), Integration Runtime, and so on.
The Security Management Tool works with PFX keystore files, and it uses AES encryption for secrets. The use of AES encryption requires a Java version higher than 8U141.
If you had an existing .JKS keystore, action should be taken to upgrade to a .PFX keystore. This happens as soon as the CLI is run against any JKS keystore. Once created, the JKS version of the keystore can be removed; although we recommend backing it up in case of issues.
The keystore conf file will work as is, but should be updated to set the keystore name to just the filename without the extension to reduce extra processing.
Location
This tool is available on the PTC Software Download page, with the ThingWorx software downloads.
Supported Versions
This tool can be used with ThingWorx 8.4.0 and later.
Permissions
This tool is intended for administrator use only. Install as needed and then remove after using.
Configuration
* 
The default-encryption-key-length must match the application configuration. In ThingWorx, it is the InternalAesCryptographicKeyLength parameter located in platform-settings.json. The default is 128, but you can use 256-bit encryption if you are using Java 1.8.0_162 or higher. If necessary, you can also use with older Java versions by updating the java policy for the key size limit.
Linux Settings:
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128

keystore {
password-file-path = "/<path to ThingworxPlatform folder>/ThingworxPlatform"
password-file-name = "keystore-password"
path = "/<path to ThingworxStorage folder>/ThingworxStorage"
name = "keystore"
}
}
}
Windows Settings:
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128

keystore {
password-file-path = "C:\\<path to ThingworxPlatform folder>\\ThingworxPlatform"
password-file-name = "keystore-password"
path = "C:\\<path to ThingworxStorage folder>\\ThingworxStorage"
name = "keystore"
}
}
}
Using the Command Line Interface Tool
Use the command line interface tool to perform specific operations outside the application to preset secrets that an application requires. The application script (security-common-cli) is provided in the distribution for Linux and Windows. There are several ways to run the command line interface tool:
• Without a configuration file — The tool starts without a security manager configured, and the commands you can run are limited. You must run the init command to configure the security manager:
# run without providing a config, will have to run init, prompt for input
./security-common-cli
• With a configuration file as the first script parameter — The tool starts and initializes the security manager with the configuration specified.
# initialize security manager with specified config, prompt for input
./security-common-cli <path to keystore>\keystore.conf
• With a configuration file and multiple other parameters — The tool runs in single use mode. It runs the provided action, and then immediately stops running. This is a way to call from a basic installer. When passing parameters on the command line that contain white space, you must enclose in single quotes for processing as a single argument. When run in command line mode, it only runs in the US locale to ensure action names are predictable.
# run one command and tool exits
./security-common-cli <config file path> <action> <parameters>
./security-common-cli keystore.conf set 'mykeyname' 'some value for my key'
* 
You can use the full path to the configuration file, or just the name of the configuration file if the configuration file is in the classpath.
Common Commands
Command
Description
help or ?
Displays usage information.
exit
Exits the tool.
config
Displays current configuration.
init <config-file>
Loads configuration.
createTokenFile<path><token>
Creates a token file.
* 
This option is available in version 1.3.1+ of the security management tool.
Secret Management Commands
Command
Description
keys
List of keys in secret provider.
get <name>
Retrieves a value from the secret provider.
set <name> <Value>
Sets a value in the secret provider.
remove <name>
Removes a value from the secret provider.
Encryption and KeyStore Commands
Command
Description
generate-key <secret-name>
Generates a new encryption key and stores it in a secret.
encrypt <encryption-key-name> <secret name> <string>
Encrypts a string using the optional key and stores it in a secret.
* 
<encryption-key-name> is optional. If an <encryption-key-name> is not specified, the default internal key is used. Files have a 10MB size limit.
decrypt<encryption-key-name> <secret name>
Decrypts a string stored in secret using the optional key.
* 
<encryption-key-name> is optional. If an <encryption-key-name> is not specified, the default internal key is used. Files have a 10MB size limit.
encryptFile <encryption-key-name> <source> <destination>
Encrypts source file, and writes it to the destination with the optional key stored as a secret.
* 
<encryption-key-name> is optional. If an <encryption-key-name> is not specified, the default internal key is used. Files have a 10MB size limit.
decryptFile <encryption-key-name> <source> <destination>
Decrypts source file, and writes it to the destination with the optional key stored as a secret.
* 
<encryption-key-name> is optional. If an <encryption-key-name> is not specified, the default internal key is used. Files have a 10MB size limit.
viewFile <encryption-key-name> <source>
Decrypts source file and view contents with optional key stored as a secret.
* 
<encryption-key-name> is optional. If an <encryption-key-name> is not specified, the default internal key is used. Files have a 10MB size limit.
migrate <password>
Migrates the KeyStore to a new generated password or password is specified.
addcert <name><path>
Loads a X.509 certificate into the keystore.
import <orchestration-keystore-config>
Imports secrets from file to secret provider.
* 
This option is available in version 1.3.1+ of the security management tool.
Example Usages
In the following example, there is no configuration on the command line:

./security-common-cli
Not initialized, use 'init <config-file>' to initialize
> init sample-keystore.conf
Loading config from file sample-keystore.conf
Secret Provider: com.thingworx.security.provider.keystore.KeyStoreProvider
KeyStore
Path: /tmp/keystore
Password File: /tmp/keystore-password
Keystore Password: 47886866662481XXXXX
> get mykey
No value found for mykey
> set mykey "this is the value"
mykey stored
> get mykey
this is the value
> remove mykey
mykey removed
> get mykey
No value found for mykey
> encrypt mykey "this is my value to encrypt"
mykey stored
> get mykey
YVljoGhjNVQjnlo/m8c+FRtZhkOb/rcfioakxxxxxx=
> decrypt mykey
this is my value to encrypt
> remove mykey
mykey removed
> exit
Complete
In the following example, there is a configuration file noted on the command line:
./security-common-cli sample-keystore.conf
Loading config from file sample-keystore.conf
Secret Provider: com.thingworx.security.provider.keystore.KeyStoreProvider
KeyStore
Path: /tmp/keystore
Password File: /tmp/keystore-password
Keystore Password: 47886866662481XXXXX
> get mykey
No value found for mykey
> set mykey "some test"
mykey stored
> get mykey
some test
> remove mykey
mykey removed
> exit
Complete
In the following example there are direct command line changes:
./security-common-cli sample-keystore.conf get mykey
Loading config from file sample-keystore.conf
No value found for mykey

./security-common-cli sample-keystore.conf set mykey "this is the value to set"
Loading config from file sample-keystore.conf
mykey stored

./security-common-cli sample-keystore.conf get mykey
Loading config from file sample-keystore.conf
this is the value to set
Usage
The KeyStore provider makes use of a secure token stored encrypted in a file to work with the KeyStore. All data written to the KeyStore is stored securely using the password. The first time the provider starts, it generates a random password value and a KeyStore file if they do not already exist.
* 
The KeyStore password and KeyStore file should be restricted to only the application user. The application user must have read and write permissions to the files.
To create a KeyStore file for storing the initial data, you must use the Security Management Tool.
1. Obtain the Security Management Tool ZIP file from the PTC Support site (in the Release 8.4 or later section).
2. Extract the contents of the ZIP file to a directory.
3. Create a configuration file with the parameters you see in the following example, and place it in the bin folder.
In this example, the file is named keystore.conf, the version of the tool is 1.0.0.36, and it is located in C:\security-common-cli-1.0.0.36\bin .
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128

keystore {
password-file-path = ":\\<path to ThingworxPlatform folder>\\ThingworxPlatform"
password-file-name = "keystore-password"
path = ":\\<path to ThingworxStorage folder>\\ThingworxStorage"
name = "keystore"
}
}
}
4. Launch a command prompt and go to the location of security-common-cli-1.0.0.36\bin.
5. Run
C:\security-common-cli-1.0.0.36\bin> security-common-cli.bat <path to keystore>\keystore.conf
set encrypt.licensing.password "add-password-here"
A password file and KeyStore are created at the configured location.
6. Open ThingworxPlatform\platform-settings.json under LicensingConnectionSettings and change the password value to encrypt.licensing.password. For example, "password": "encrypt.licensing.password". This password signals the ThingWorx platform to look up the encrypted licensing password in the keystore when it is encountered.
Changing the KeyStore Password
It is also possible to migrate the KeyStore password to a new password using the Security Management Tool. When the password is changed, the application can no longer use keys, as they are migrated until the applications KeyStore password is reset. Currently this requires an application restart.
1. Stop the application using the KeyStore.
2. Run the Security Management Tool script with the KeyStore configuration.
3. Run the migrate command. This generates a new password, moves all data to the new password, and updates the secure file with the new password.
4. Restart the application to load the new KeyStore password.
Was this helpful?