Using a Custom Certificate and Private Key
As of v.5.4.10, the EMS supports v.1.1.1j of OpenSSL. All commands contained in this section use OpenSSL. Typically shipped with Linux systems, OpenSSL can also be downloaded from https://www.openssl.org/. This topic is written to work with Linux, but should work with Windows as well. PTC recommends using Linux to create the certificate and key because it is easier to obtain the OpenSSL binaries and configuration files required. On Windows you need to either build OpenSSL from source or use a third-party installer. An informal list of third-party installers can be found here: https://wiki.openssl.org/index.php/Binaries.
The following sections take you through the steps of creating a private key, a self-signed certificate, a Certificate Signing Request (CSR), a Certificate Authority (CA), a custom CA certificate chain, and finally through configuring EMS to use that certificate chain or another one. Click the title of a section to display its content. To hide the content, click the title again.
Creating a Private Key
A private key is used to identify the EMS when it communicates with the LSR or other edge devices. To create a private key, use the following OpenSSL command:
openssl genrsa -aes256 -out private_key.pem 2048
When prompted, as shown below, enter a passphrase to be used to decrypt the private key:
openssl genrsa -aes256 -out private_key.pem 2048
Generating RSA private key, 2048 bit long modulus
........................................................................................................................................++
..................................................++
e is 65537 (0x10001)
Enter passphrase for private_key.pem:
Verifying - Enter passphrase for private_key.pem:
At this point you have a private key that can be used with the EMS or LSR. You now have a couple of options for creating or acquiring a certificate For testing purposes, you may want to create a self-signed certificate. For production purposes, you should create a Certificate Signing Request (CSR), submit it to a Certificate Authority, and then create a certificate chain.
Creating a Self-Signed Certificate - for Testing Purposes ONLY
 | For testing purposes ONLY, you can create a self-signed certificate to use between the EMS and the ThingWorx Platform or between the EMS and Lua Script Resource (LSR). PTC strongly recommends against using self-signed certificates in production, since they cannot be validated. |
Run the following command to generate a Certificate Signing Request called request.csr that can be used to create a self-signed certificate.
openssl req -key private_key.pem -new -x509 -days 365 -out self_signed_certificate.crt
Output similar to the following should be displayed when you run the command. When prompted, fill in the passphrase for the private key and then the X509 identity information:
openssl req -key private_key.pem -new -x509 -days 365 -out self_signed_certificate.crt
Enter passphrase for private_key.pem:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:MA
Locality Name (eg, city) []:Boston
Organization Name (eg, company) [Internet Widgits Pty Ltd]:PTC
Organizational Unit Name (eg, section) []:Thingworx
Common Name (e.g. server FQDN or YOUR name) []:EEexample Certificate
Email Address []:example@ptc.com
Note that the -days 365 argument is used, which means that this certificate is valid for one year. Consult the OpenSSL documentation for v.1.1.1 for more details on how to customize the length of time your certificate is valid.
You now have a self-signed certificate that you can use with the EMS and LSR. To inspect the contents of the certificate, use the following command:
openssl x509 -in self_signed_certificate.crt -text -noout
This command produces output similar to the following, which shows the X509 identity information entered earlier in the Issuer and Subject fields:
openssl x509 -in self_signed_certificate.crt -text -noout
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 10278892931034865755 (0x8ea5f6a92e9b605b)
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=US, ST=MA, L=Boston, O=PTC, OU=Thingworx, CN=Example
Certificate/emailAddress=example@ptc.com
Validity
Not Before: June 2 20:46:33 2020 GMT
Not After : June 30 20:46:33 2021 GMT
Subject: C=US, ST=MA, L=Boston, O=PTC, OU=Thingworx, CN=Example
Certificate/emailAddress=example@ptc.com
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:a4:ed:ba:e0:f7:97:21:ce:b3:97:0f:68:49:1f:
d7:fa:de:48:d8:98:37:38:a4:ef:72:5d:c0:1c:e8:
23:77:dc:b6:bc:8a:3d:b0:b0:5a:45:77:f7:d4:1e:
78:c9:f3:e0:4e:ce:4d:1d:47:6c:09:a2:18:b8:32:
df:16:ff:24:34:b6:84:3f:3e:eb:65:f7:96:77:a4:
ad:eb:e2:38:f6:3b:24:63:64:45:bb:37:1f:71:81:
59:9d:81:bb:d2:9e:f6:03:cc:d3:05:30:95:4d:94:
96:ba:35:df:c3:7b:25:12:5a:bd:a0:b6:51:47:a8:
54:5d:2f:18:e2:3e:e8:39:1c:a6:3c:cc:2c:b2:7f:
25:4a:12:8c:27:d5:73:c2:95:71:e6:ec:9a:9a:01:
70:c2:09:6f:15:f7:e4:ad:c2:dc:d1:9b:55:5f:b6:
d4:a8:ca:e3:a8:45:9a:f9:84:c7:dd:17:c7:a3:bb:
19:e3:ef:75:53:2c:24:01:5c:31:c6:ad:1a:bd:e3:
76:e5:57:6e:4d:4e:c6:8f:a9:52:cb:52:01:5d:c2:
3d:b4:3b:62:8f:dd:20:2f:e9:b3:2e:32:cb:f6:c0:
c0:38:e1:9b:16:4a:6d:45:45:24:c7:b4:a9:12:75:
9f:7c:df:a8:20:96:31:22:42:53:ae:8e:5b:0d:86:
a7:2b
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Subject Key Identifier:
60:24:2D:3F:C3:62:74:63:21:9E:71:06:4C:C3:8F:
D8:86:19:80:03
X509v3 Authority Key Identifier:
keyid:60:24:2D:3F:C3:62:74:63:21:9E:71:06:4C:C3:8F:
D8:86:19:80:03
X509v3 Basic Constraints:
CA:TRUE
Signature Algorithm: sha256WithRSAEncryption
6b:95:88:b4:6f:13:d6:2f:56:29:cb:1c:fb:3f:95:c0:a2:71:
32:96:1c:87:dd:47:7a:c8:71:26:c4:b6:cf:f6:2a:ac:ce:07:
03:51:b5:d4:b5:22:91:d4:4a:8c:12:7b:8e:1e:4c:4b:10:51:
da:d4:9e:c0:43:0d:bf:dd:08:60:b8:d0:35:10:d7:1a:7a:72:
e2:29:c3:9a:4c:89:20:53:f3:5e:5c:e8:87:d0:1c:bb:8f:67:
ab:d6:b2:ce:29:64:dc:27:bd:5d:a5:71:e4:6c:c2:f5:5e:0a:
9c:fd:c3:7a:f3:74:6c:ba:ae:bb:7b:86:95:e0:00:0d:e9:e2:
7a:18:3b:a5:39:c8:77:15:23:39:8e:1b:40:c1:2f:5c:fc:dc:
24:6a:e8:7b:f9:14:93:7d:1a:4b:f0:f5:54:34:a1:23:16:44:
f8:43:99:ba:52:cf:5c:67:70:94:e0:7d:2d:5f:d5:a3:95:ac:
b5:ad:2c:07:6e:05:c3:a7:37:8d:f4:7f:00:81:48:08:81:13:
45:ec:23:8c:0d:79:ce:da:68:c8:91:01:66:e4:53:7b:8f:f7:
0e:55:4e:08:91:77:d2:79:7b:df:05:40:f3:a6:9d:de:98:28:
3d:00:fa:c9:de:c5:f1:1e:d6:ef:43:05:a5:0b:f3:b5:cc:b2:
e2:ff:cc:65
 | When you use a self signed certificate, you must enable self-signed certificate support in the config.json file for the EMS: "certificates": { "allow_self_signed": true } and in the config.lua file for the LuaScriptResource (LSR): scripts.rap_deny_selfsigned = false Do not use this configuration in production! |
Creating a Certificate Signing Request (CSR)
For self-signed certificates, you can use the OpenSSL req command to create self-signed certificates for use as root CAs. Refer to the OpenSSL 1.1.1 documentation for this command.
If you are purchasing a certificate from a commercial organization or your company runs its own certificate authority, you most likely have to create a Certificate Signing Request (CSR) to acquire a certificate. This process should be detailed by whoever manages the signing request.
Creating a Certificate Authority (CA)
Creating a Certificate Authority (CA) can be the most flexible, but also the most complicated option, the details of which are outside the scope of this guide. Creating your own CA allows you to control the entire chain of trust. The OpenSSL Certificate Authority guide to accomplish this can be found here.
Creating a Custom CA Certificate Chain
To validate that the ThingWorx Platform (server) with which it is communicating is trusted, an Edge device (client) must have a list of trusted certificate authorities that are expected from the ThingWorx Platform (server). This list is referred to as a Certificate Authority list and also as a certificate chain.
To create a certificate chain, create a file that contains all the Certificate Authority (CA) certificates that you want your agent to trust. This file will typically contain the root and intermediate CA certificates that are used on the ThingWorx Platform server with which the EMS (client) communicates, as well as the root and intermediate CA certificates that were used to create the certificates used by the EMS and the LSR. Here is an example of a Certificate Authority chain:
-----BEGIN CERTIFICATE-----
(Your EMS Server Certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(The Intermediate CA Certificate of the issuer of the EMS Server Certificate)
-----END CERTIFICATE-----
Store the chain in a PEM-encoded certificate file. This file allows the client to validate each node in the certificate chain presented by the server during the TLS handshake. If you have certificate validation enabled, you must create and configure a certificate chain. If you are using a self-signed certificate, you do not need to configure a chain.
Certificate validation requires that root keys be distributed independently, so a self-signed certificate that specifies the root certificate authority may optionally be omitted from the chain. In this case, it is assumed that the remote device must already possess the root certificate authority in order to validate it.
Configuring the EMS to Use the Certificate Chain
To use the certificate chain, you can enable it in the same way you would configure a certificate, using the following options in config.json for the EMS and in config.lua for the Lua Script Resource. The following examples show what to add in both of these configuration files:
EMS Example from config.json
"certificates": {
"cert_chain": "/path/to/certificate_chain/file"
}
LSR example from config.lua
scripts.script_resource_certificate_chain = "/path/to/certificate_chain/file"
Configuring the EMS to Use a Different Certificate Chain for Edge to Edge Communications (Optional)
The EMS provides a parameter called http_client_ca_certs that allows the use of a separate Certificate Authority (CA) certificate file that will only be used for Edge-to-Edge HTTPS connections. If this option is not used, the default CA certificate list set in the cert_chain property that is used to validate the platform connection will be used. This parameter is in the certificates group in the EMS configuration file.
Like the cert_chain property, the http_client_ca_certs is set in the certificates group of the EMS configuration file.
"certificates": {
"cert_chain": "/path/to/ca_cert/file"
. . .
"http_client_ca_certs_: "/path/to/ca_cert/file"
}