Setting Up Security for the EMS
If you are installing the EMS for the first time with v.5.4.5 or later and have the custom certificates and private keys that you want to use for communications between the EMS and the ThingWorx Platform and for communications between the EMS and the LSR that is running on the devices behind the EMS, this topic is for you. If you are migrating a previous release of the EMS and LSR and were using the built-in certificate, refer to Migrating from the EMS/LSR Built-in Certificates. If you do not have custom certificates and private keys, refer to Using a Custom Certificates before continuing with the rest of this topic.
The following sections guide you through setting up EMS to use certificates. Click the title of a section to display its content. To hide the content, click the title again.
Setting Up EMS to Use Certificates
The properties in the certificates group of the configuration file specify whether certificates are validated for the connection between the EMS and your ThingWorx Platform instance. This group and its properties are shown here:
"certificates": {
"validate": true,
"allow_self_signed": false,
"disable_hostname_validation": false
"cert_chain": " /path/to/ca/cert/file",
"client_cert": "/path/to/client/cert/file",
"key_file": "/path/to/key/file",
"key_passphrase": "some_encrypted_passphrase",
"cipher_suite": "ALL:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!PSK:!DSS:!RC4:!SEED:!ADH:!IDEA:!3DES:!SRP",
"http_client_ca_certs": "/path/to/ca/cert/file",
"validation_criteria": {
"Cert_Common_Name": "common name",
"Cert_Organization": "organization name",
"Cert_Organizational_Name": "organizational name",
"CA_Cert_Common_Name": "cert common name",
"CA_Cert_Organization": "cert organization",
"CA_Cert_Organizational_Name": "cert organizational name"
}
"http_client_ca_certs_: "/path/to/ca_cert/file"
"fingerprint_allowlist" : [
""E6:EF:5D:37:22:FC:EF:EA:4B:22:92:45:BD:49:D2:29:3D:84:19:BC:
C3:45:23:A1:22:A4:01:20:9D:03:E6:47",
"D1:BA:B0:17:66:6D:7F:42:7B:91:1E:22:7E:3A:27:D2:EF:5D:37:22:FC:E
F:EA:4B:22:92:45:BD:01:7E:92:52"
]
},
 | If you are using v.5.4.8 or later of the EMS and LSR, secrets such as passphrase, password, and application keys are automatically encrypted. For details, refer to Automatic Configuration Encryption. If you are using an older version of the EMS and LSR, refer to Encrypting Application Keys, Passwords, and Passphrases. For examples of secure configurations for communications between the EMS and the LSR, refer to Examples of Configuring Secure Communications between the EMS and an LSR. These examples are presented in order of least secure (testing purposes ONLY) to most secure (strongly recommended for production environments). |
The following table describes the properties configuring SSL/TLS certificates. Refer to the section below for definitions of the validation criteria.
 | When specifying the paths to any certificate, use forward slashes (/) for a Linux platform and either backslashes with escapes ("d:\\path\\to\\ca\\cert\\file") or forward slashes ("d:/path/to/ca/cert/file") for Windows platforms. |
Property | ThingWorx Base Type | Description | ||
|---|---|---|---|---|
validate | BOOLEAN | Whether or not to perform validation on certificates presented by a ThingWorx Platform instance. The default value of this property is true. For production, enabling validation is strongly recommended. If you set this property to true, you must create and configure a Certificate Authority (CA) list and specify the path to the file as the value of the cert_chain property. | ||
allow_self_signed | BOOLEAN | Whether or not to permit self-signed certificates to be used. The default value of this property is false. For production, allowing self-signed certificates is strongly discouraged. . | ||
disable_hostname_validation | BOOLEAN | Whether or not to use TLS host name validation. The default value of this property is false, meaning that this validation is enabled. If you want to disable it (not recommended), set this property to true. For more information, refer to TLS Host Name Validation. | ||
cert_chain | STRING | Certificate Authority list to be used to validate the ThingWorx Platform ("server") certificate. Used if allow_self_signed is false and validate is true. You must specify the CA list here if you set validate to true. Here is an example for an EMS running on Linux: "cert_chain": "/path/to/ca/cert/file",
| ||
cipher_suite | STRING | The cipher suites for the Edge device to use when communicating with the ThingWorx Platform. The default setting is ALL. This option supports the OpenSSL cipher list format, which you can find at https://www.openssl.org/docs/man1.0.2/apps/ciphers.html. | ||
client_cert (optional) | STRING | The path to the X.509 certificate file for the client. If you are using an X.509 certificate file, you need to set the validation_criteria property. | ||
http_client_ca_certs | STRING | A list of Certificate Authority certificates to use when validating TLS connections at the Edge. If left unset, the CA certificates specified for the property, cert_chain will be used. The CA Certificates are used if allow_self_signed is set to false and validate is set to true. | ||
validation_criteria | STRING | Refer to the section below for details about this property. | ||
fingerprint_allowlist | N/A | Certificate fingerprint validation is a security feature that allows a user to restrict HTTPS communication to a known set of trusted server endpoints in addition to TLS certificate validation. This feature is not enabled by default. To enable this feature, you must add the fingerprint_allowlist property with an array of strings to the config.json file of each edge microserver with which you want to communicate. If you do not include this configuration option in the config.json file, it is not enabled.
| ||
The following properties are all passed to the underlying C SDK and are not used by the EMS. They are associated with the WebSocket connection | ||||
key_file (optional) | STRING | The path to the key file to load for client certificates (supports .pem, .p8, and .p12 files). If you need to create a private key file, refer to Creating a Private Key. | ||
key_passphrase (optional) | STRING | A string password for opening the key file. It is strongly recommended that the passphrase be encrypted. To encrypt this passphrase, refer to Encrypting Application Keys, Passwords, and Passphrases. | ||
Validation Criteria
To validate a certificate, you can configure the fields of the certificate that should be validated:
• Subject common name
• Subject organization name
• Subject organizational unit
• Issuer common name
• Issuer organization name
• Issuer organizational unit
When creating a Certificate Signing Request (CSR), you are prompted for the fields that need to be validated. The following definitions may help you determine the values for these fields:
• Common Name — Typically, a combination of the host and domain names, the value of these fields looks like “www.your_site.com” or “your_site.com”. Certificates are specific to the Common Name that they have been issued to at the Host level. This Common Name must be the same as the web address that the EMS accesses when connecting to a ThingWorx Platform using SSL/TLS. If the platform and the EMS are located on an intranet, the Common Name can be just the name of the host machine of the platform.
• Organization Name — Typically, the name of the company.
• Organizational Unit — Typically, a department or other such unit within a company. For example, IT.
TLS Host Name Validation
The EMS supports TLS host name validation. This security feature compares the requested host name with subject identifiers in the server certificate, such as the subject common name (CN) and subject alternative names. TLS host-name validation occurs during the TLS Handshake. If the host name on the server certificate does not exactly match the host provided in the EMS configuration, the TLS handshake fails with the error, TW_SOCKET_INIT_ERROR, and the connection to the ThingWorx Platform fails.
This feature is enabled by default. To disable it, add the disable_hostname_validation property in the certificates group in the config.json file for your EMS and set it to true, as shown here:
"certificates" : {
. . .
"disable_hostname_validation" = true
. . .
Encrypting Application Keys, Passwords, and Passphrases
The EMS and LSR, v.5.4.8 and later, use a different data security library for encrypting data at rest than previous releases. This library automatically encrypts configuration files on the first startup of the EMS or LSR. For details, refer to Protecting Data with Encryption. With this library you can, but no longer need to, run the wsems.exe -encrypt command to encrypt an application key, certificate password, or keystore passphrase.
For versions prior to v.5.4.8, the legacy data at rest encryption, AES, is supported. In addition, you can improve security for an application by encrypting the application key, certificate password, and keystore passphrase before adding them to the configuration file for EMS. Follow these steps:
1. Open a shell or command prompt, navigate to the EMS installation, and enter the following:
wsems.exe -encrypt String_to_Encrypt
where String_to_Encrypt is the application key, password, or passphrase to encrypt.
2. Once the output is generated, copy the encrypted string and paste it so that it replaces the current value of the related property in the configuration file. Make sure that the encrypted string is enclosed in double quotation marks.
For examples of medium and high security configurations for the EMS and LSR, refer to Medium Security and High Security.
Configuring the Cipher Suite Set
Starting with v.5.4.5 of the EMS, you can specify what cipher suites are used by the Edge device when communicating with the ThingWorx Platform. This configuration option supports the OpenSSL Cipher List form, as described at https://www.openssl.org/docs/man1.1.0/apps/ciphers.html.
This configuration option should be placed in the certificates group in the config.json file for your EMS:
"certificates": {
...
"cipher_suite": "ALL:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!PSK:!DSS:!RC4:!SEED:!ADH:!IDEA:!3DES:!SRP",
...
},
Configure FIPS Mode for EMS 5.4.0 and earlier
Version 1.1.1 of OpenSSL is provided in the distribution bundle of the EMS starting with version 5.4.7 of the EMS. This version of OpenSSL does not support FIPS mode. If you require FIPS mode, make sure that you have downloaded version 5.4.0 or earlier of the EMS that supports FIPS mode. Refer to the ThingWorx Edge MicroServer Support Matrix for a table of versions of EMS and the versions of OpenSSL they support. The rest of this section is for users of v.5.4.0 or earlier of the EMS.
By default FIPS mode is disabled. To enable FIPS mode, you need to set the FIPS option in your config.json file. The EMS checks if FIPS mode is enabled on startup.
In release 5.4.0, a “switch” was added in the form of a group and property to enable or disable FIPS mode. If you created the config.json file for your EMS using config.json.minimal as the starting point, you need to add the group to your configuration file and change the value of the enabled property to true, as follows:
"fips" " {
"enabled" : true
},
If you used config.json.complete as your config.json file, the group and property are already present in the file. Set the value of the enabled property to true to enable FIPS mode, as shown above.
Should you need to disable or enable FIPS mode at any time, open the config.json file for your EMS, and locate the fips group. To disable FIPS mode, set the enabled property to false, as shown here:
"fips" : {
"enabled" : false
},