Protecting Data with Encryption
As of v.5.4.8, the EMS and LSR use a new data protection library. This data security library uses the XChaCha20-Poly1305 Cipher for encryption of data at rest to provide automated encryption of application keys, passwords, and other sensitive information in configuration files. Data is protected by a unique data protection key, dp.dat, that is automatically created by the EMS or LSR the first time it runs. Any existing encrypted data in configuration files is automatically converted to use the updated encryption method.
This topic first explains how to enable and disable encryption for the EMS. It then provides information about using the new data protection library for automatic encryption with both the EMS and LSR, in the following sections. Click the title of a section to display its content. Click the title again to hide the content:
How to Enable and Disable Encryption
You enable or disable encryption in the ws_connection group of the configuration file. By default, the EMS always attempts to connect to a ThingWorx Platform instance, using SSL/TLS (that is, encryption is enabled).
 | The code samples below are provided for example purposes only. |
To enable encryption, specify the properties as shown below:
"ws_connection": {
"encryption" : "ssl"
}
To disable encryption (NOT recommended), specify the properties as shown below:
"ws_connection": {
"encryption" : "none"
}
 | Always enable encryption. Otherwise, the EMS and LSR will log warning message (console). |
The ws_connection group contains the following property:
Property | Description | ||
|---|---|---|---|
encryption | Whether or not encryption is enabled for communications with the ThingWorx Platform instance, and the type of encryption used. Valid values are: • none • ssl
|
Automatic Configuration Encryption
As of v.5.4.8, the EMS provides a new automatic encryption feature that automatically encrypts sensitive data in configuration files on start-up. This feature is designed to make it easy to update existing configuration files that use either the legacy encryption format, or no encryption at all. This feature is always enabled and cannot be disabled.
When the EMS or LSR is started, all data previously encrypted with the legacy encryption format is automatically updated to use the latest format. Additionally, any plaintext values considered to be sensitive, such as application keys, passwords, or passphrases for private keys are also automatically encrypted.
Modifying Encrypted Configuration Properties
You can replace a parameter that has been encrypted in a configuration file with a new plaintext value, and it will be automatically encrypted when the EMS or LSR starts.
Data Security
As of v.5.4.8, the EMS automatically appends a new property, called "Data Security Key Hash", to the configuration files for the EMS and LSR The EMS and LSR check the value of this property to detect any potential modification to the data security key between start ups. If this value is determined to be different than the value expected, a warning message is written to the log. In addition, decryption may fail if the key has changed.
This field should not be modified by users and can be ignored. The value appears at the end or your configuration file
• data_security.key_hash in EMS config.json
• scripts.data_security_key_hash in LSR config.lua