ThingWorx WebSocket-based Edge MicroServer (WS EMS) and Lua Script Resource (LSR) > Configuring Secure Connections (SSL/TLS and FIPS Mode) > Setting Up Security for the WS EMS
Setting Up Security for the WS EMS
If you are installing the WS 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 WS EMS and the ThingWorx platform and for communications between the WS EMS and the LSR that is running on the devices behind the WS EMS, this topic is for you. If you are migrating a previous release of the WS EMS and LSR and were using the built-in certificate, see Migrating from the WS EMS/LSR Built-in Certificates. If you do not have custom certificates and private keys, see Using a Custom Certificate and Private Key before continuing with the rest of this topic.
This topic provides the following information:
Setting Up WS EMS to Use Certificates
Properties to Set in config.json for Security
Validation Criteria
Password/Passphrase Encryption
Configuring the Cipher Suite Set
A Note about Cipher Suites (Java 7)
Configuring FIPS Mode
Setting Up WS EMS to Use Certificates
The properties in the certificates group of the configuration file specify whether certificates will be validated for the connection between the WS EMS and your ThingWorx platform instance. This group and its properties follow:

"certificates": {
"validate": true,
"allow_self_signed": 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",
"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"
To encrypt a passphrase, password, or Application key, see Encrypting Application Keys, Passwords, and Passphrases. For examples of secure configurations for communications between the WS EMS and the LSR, see Examples of Configuring Secure Communications between the WS 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 lists and describes the properties configuring SSL/TLS certificates. See 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.
Properties to Set in config.json for Security
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 list and specify the path to the file as the value of the cert_chain property. See Createing and Using a Custom Certificate Authority (CA) List for details on creating a Certificate Authority list file.
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. If you need to create a self-signed certificate for testing purposes, see Creating a Self-Signed Certificate.
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 a WS EMS running on Linux:
"cert_chain": "/path/to/ca/cert/file",
To learn how to create a Certificate Authority list, see Creating and Using a Custom Certificate Authority List
The cert_chain property expects a string that specifies a single Certificate Authority list file. If you want to load multiple certificates, add them to the Certificate Authority file and specify the path to that file, as shown here. The WS EMS will load multiple certificates from that CA list file.
client_cert (optional)
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. See Validation Criteria below.
The following properties are all passed to the underlying C SDK and are not used by the WS EMS. They are associated with the WebSocket connection
key_file (optional)
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, see Creating a Private Key.
key_passphrase (optional)
A string password for opening the key file. It is strongly recommended that the passphrase be encrypted. To encrypt this passphrase, see Encrypting Application Keys, Passwords, and Passphrases.
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 See also Configuring the Cipher Suite Set below.
This option is supported only by the OpenSSL releases of the WS EMS. It is not supported by the axTLS releases of the WS EMS.
See the section below for details about this property.
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 will 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 “” or “”. 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 WS EMS will access when connecting to a ThingWorx platform instance using SSL/TLS. If the platform instance and the WS EMS are located on an intranet, the Common Name can be just the name of the host machine of the instance.
Organization Name — Typically, the name of the company.
Organizational Unit — Typically, a department or other such unit within a company. For example, IT.
Encrypting Application Keys, Passwords, and Passphrases
The WS EMS supports data at rest encryption (AES), so you can improve security for your application by encrypting the Application Key, certificate password, and keystore passphrase before adding them to the config.json file for a WS EMS. To encrypt a password for an Application Key, a certificate, or a passphrase for a keystore, follow these steps:
1. Open a shell or command prompt, navigate to the WS EMS installation, and enter the following:
wsems.exe -encrypt myPasswordString
where myPasswordString is the Application Key, password, or passphrase that you want to encrypt.
2. Once the encryption generates output, copy the encrypted string and paste it so that it replaces the current value of the related property in the config.json file. Make sure that the encrypted password is enclosed in the double quotation marks.
For examples of medium and high security configurations for the WS EMS and LSR, see Medium Security and High Security.
Configuring the Cipher Suite Set
Starting with v.5.4.5 of the WS EMS, you can specify what cipher suites are used by thee Edge device when commnicating with the ThingWorx platform. This configuration option supports the OpenSSL Cipher List form, as described at
This option is supported only on WS EMS releases that use OpenSSL. The axTLS release will ignore this option.
This configuration option should be placed in the certificates group in the config.json file for your WS EMS:

"certificates": {
"cipher_suite": "ALL:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!PSK:!DSS:!RC4:!SEED:!ADH:!IDEA:!3DES:!SRP",
A Note about Cipher Suites with ThingWorx Platform (Java 7)
If your application communicates with an instance of the ThingWorx platform that uses Java 7, the cipher suite list should include !kEDH (as shown below) to disable ephemeral Diffie-Hellman ciphers . Otherwise, ephemeral Diffie-Hellman (EDH) key exchange will fail, and your WS EMS will be unable to connect to the platform.

Configure FIPS Mode
To use FIPS mode, make sure that you have downloaded one of the WS EMS distribution bundles that has openssl in the name of the file. This distribution bundle provides support for the OpenSSL library and the FIPS-140-2–validated cryptographic module (Certificate#1747, FIPS Object Module 2.0.2) on supported Windows and Linux platforms.
By default FIPS mode is disabled. To enable FIPS mode, you need to set the FIPS option in your config.json file. The WS EMS will check if FIPS mode is enabled on startup.
As of release 5.4.0, a “switch” has been added in the form of a group and property to enable or disable FIPS mode. If you created the config.json file for your WS 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 WS EMS, and locate the fips group. To disable FIPS mode, set the enabled property to false, as shown here:

"fips" : {
"enabled" : false