ThingWorx WebSocket-based Edge MicroServer (WS EMS) and Lua Script Resource (LSR) > Configuring Secure Connections (SSL/TLS and FIPS Mode) > Using a Custom Certificate and Private Key
  
Using a Custom Certificate and Private Key
All commands contained in this section use OpenSSL. OpenSSL is typically shipped with Linux systems, but can be downloaded if it is not installed on your system 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 OpenSSL binaries and configuration files required. On Windows you need either to build OpenSSL from source, or to use a third-party installer (an informal list can be found here: https://wiki.openssl.org/index.php/Binaries).
To use custom certificates, private keys, certificate chains, and Certificate Authority list, see the following sections:
1. Creating a Private Key
2. Creating a Self-Signed Certificate — for Testing Purposes ONLY
3. Creating a Certificate Signing Request (CSR)
4. Creating a Certificate Authority (CA)
5. Creating a Certificate Chain
6. Creating and Using a Custom Certificate Authority List
Creating a Private Key
A private key is used to identify the WS EMS when it communicates with the LSR or other edge device. To create a private key, use the following 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 WS EMS or LSR. You now have a couple of options for creating or acquiring a certificate
Creating a Self-Signed Certificate - for Testing Purposes ONLY
For testing purposes ONLY, you can create a self-signed certificate to use with either the WS EMS or LuaScriptResource. 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 -new -key private_key.pem -sha256 -out request.csr
When prompted, fill in the passphrase and then the X509 identity information:

openssl req -new -key private_key.pem -sha256 -out request.csr
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) []:
EMS/LSR Web Server
Email Address []:
example@ptc.com

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:

An optional company name []:
Once you have created the certificate signing request, you can generate a self-signed certificate using the following command:

openssl x509 -req -days 365 -in request.csr -signkey private_key.pem -sha256 -out self_signed_certificate.pem
Note that the -days 365 argument is used, which means this certificate is valid for one year. Consult the OpenSSL user's manual for more details on how to customize the length of time your certificate is valid.
You should see something similar to the following output when you run the command. When prompted, enter the passphrase for your private key file:

openssl x509 -req -days 365 -in request.csr -signkey private_key.pem -sha256 -out self_signed_certificate.pem
Signature ok
subject=/C=US/ST=MA/L=Boston/O=PTC/OU=Thingworx/CN=EMS/LSR Web Server/emailAddress=example@ptc.com
Getting Private key
Enter pass phrase for private_key.pem:
You now have a 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.pem -text
This command products 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.pem -text
Certificate:
Data:
Version: 1 (0x0)
Serial Number: 10416457121854115677 (0x908eb0904633cf5d)
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=US, ST=MA, L=Boston, O=PTC, OU=Thingworx, CN=EMS/LSR Web Server/emailAddress=example@ptc.com
Validity
Not Before: Dec 12 16:19:32 2018 GMT
Not After : Dec 12 16:19:32 2019 GMT
Subject: C=US, ST=MA, L=Boston, O=PTC, OU=Thingworx, CN=EMS/LSR Web Server/emailAddress=example@ptc.com
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:9f:4a:cd:06:68:7f:2d:99:2a:9f:fb:24:79:be:
c4:59:ad:84:d5:c6:4d:7e:37:56:ef:5e:d6:94:26:
32:4b:67:0e:2a:27:d9:67:20:67:5a:55:41:b1:06:
0f:13:55:66:9a:ab:e7:5a:ab:fd:a7:e9:71:f2:e8:
5b:15:97:e8:f5:d9:31:d0:1f:bb:65:fd:fd:de:f4:
8e:1e:85:75:db:78:7c:a7:1b:8a:27:1c:df:67:76:
c8:e1:7e:30:b0:3f:7d:59:9a:be:ab:be:8c:8f:64:
f1:9f:50:b6:58:1b:d5:c2:a3:56:84:f2:6f:34:fc:
2d:4f:5c:7a:f5:25:b9:c8:f5:13:6e:d4:d5:23:92:
03:ee:a5:22:8d:ba:d6:58:ff:f5:62:b2:d1:b1:3c:
05:63:16:0a:73:af:11:e4:87:f2:6d:1d:05:a1:2b:
50:09:0f:92:78:12:9d:6e:b6:36:86:34:4f:f0:ea:
fb:5a:59:57:6b:b5:f9:c5:42:38:fb:47:73:09:95:
53:da:54:bc:86:f8:02:ba:70:46:d9:91:d1:10:9b:
63:5d:24:a9:60:ca:19:0d:ad:6d:90:71:f6:66:19:
37:22:45:53:b7:a6:1b:84:8f:5c:b0:bb:29:ce:46:
74:80:e0:2a:89:0c:73:f0:e8:96:8b:a4:98:97:99:
0d:43
Exponent: 65537 (0x10001)
Signature Algorithm: sha256WithRSAEncryption
7b:f2:b1:ef:38:f0:51:6b:eb:15:47:75:85:94:27:a4:93:d7:
3b:2a:fd:a6:af:3a:a8:54:6b:53:3e:2f:5e:9d:c4:80:90:fc:
8d:40:61:10:ad:09:a5:a7:6e:08:b4:ef:af:63:31:69:72:5a:
49:de:24:1b:28:c1:b8:4a:a2:09:af:f3:c5:ad:75:79:d2:17:
90:19:82:30:8c:55:ef:21:b1:bb:df:21:aa:65:39:5d:8a:f4:
1c:2f:a7:5b:f4:20:c7:1a:90:2e:ef:06:a7:cf:c7:63:1d:a3:
01:70:15:f1:ff:97:01:f2:0e:25:b7:05:62:92:0b:b9:48:a8:
81:5e:41:74:10:35:42:b0:30:9f:ee:81:31:77:99:e8:fa:df:
30:13:b3:f9:a6:de:c4:31:02:0a:08:55:ff:90:10:72:ff:14:
15:71:c0:90:b9:32:2f:43:5a:73:49:e5:8f:48:27:2a:47:5d:
4d:40:38:6a:f2:b6:68:29:b0:fa:4a:69:96:16:be:0c:a4:95:
2d:38:01:d9:aa:da:e8:27:7a:49:86:18:0f:e7:cc:17:4d:98:
0d:fe:b9:f8:04:db:3c:b2:15:51:4b:fc:cf:bf:81:c8:60:9f:
51:a9:fa:21:e4:d6:7e:cc:8f:1b:a7:45:02:a5:e3:32:92:93:
b0:8e:75:b1
-----BEGIN CERTIFICATE-----
MIIDkjCCAnoCCQCQjrCQRjPPXTANBgkqhkiG9w0BAQsFADCBijELMAkGA1UEBhMC
VVMxCzAJBgNVBAgMAk1BMQ8wDQYDVQQHDAZCb3N0b24xDDAKBgNVBAoMA1BUQzES
MBAGA1UECwwJVGhpbmd3b3J4MRswGQYDVQQDDBJFTVMvTFNSIFdlYiBTZXJ2ZXIx
HjAcBgkqhkiG9w0BCQEWD2V4YW1wbGVAcHRjLmNvbTAeFw0xODEyMTIxNjE5MzJa
Fw0xOTEyMTIxNjE5MzJaMIGKMQswCQYDVQQGEwJVUzELMAkGA1UECAwCTUExDzAN
BgNVBAcMBkJvc3RvbjEMMAoGA1UECgwDUFRDMRIwEAYDVQQLDAlUaGluZ3dvcngx
GzAZBgNVBAMMEkVNUy9MU1IgV2ViIFNlcnZlcjEeMBwGCSqGSIb3DQEJARYPZXhh
bXBsZUBwdGMuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAn0rN
Bmh/LZkqn/skeb7EWa2E1cZNfjdW717WlCYyS2cOKifZZyBnWlVBsQYPE1Vmmqvn
Wqv9p+lx8uhbFZfo9dkx0B+7Zf393vSOHoV123h8pxuKJxzfZ3bI4X4wsD99WZq+
q76Mj2Txn1C2WBvVwqNWhPJvNPwtT1x69SW5yPUTbtTVI5ID7qUijbrWWP/1YrLR
sTwFYxYKc68R5IfybR0FoStQCQ+SeBKdbrY2hjRP8Or7WllXa7X5xUI4+0dzCZVT
2lS8hvgCunBG2ZHREJtjXSSpYMoZDa1tkHH2Zhk3IkVTt6YbhI9csLspzkZ0gOAq
iQxz8OiWi6SYl5kNQwIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQB78rHvOPBRa+sV
R3WFlCekk9c7Kv2mrzqoVGtTPi9encSAkPyNQGEQrQmlp24ItO+vYzFpclpJ3iQb
KMG4SqIJr/PFrXV50heQGYIwjFXvIbG73yGqZTldivQcL6db9CDHGpAu7wanz8dj
HaMBcBXx/5cB8g4ltwVikgu5SKiBXkF0EDVCsDCf7oExd5no+t8wE7P5pt7EMQIK
CFX/kBBy/xQVccCQuTIvQ1pzSeWPSCcqR11NQDhq8rZoKbD6SmmWFr4MpJUtOAHZ
qtroJ3pJhhgP58wXTZgN/rn4BNs8shVRS/zPv4HIYJ9Rqfoh5NZ+zI8bp0UCpeMy
kpOwjnWx
-----END CERTIFICATE-----
* 
When you use a self signed certificate, you must enable self-signed certificate support in the config.json file for the WS EMS:

"certificates": {
"allow_self_signed": true
}
and in the config.lua file for the LuaScriptResource (LSR):

scripts.rap_deny_selfsigned = false
Creating a Certificate Signing Request (CSR)
If you are purchasing your 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. A detailed guide to accomplish this can be found here.
Creating a Certificate Chain
If you have a certificate that was issued by a CA and is therefore not self-signed, create a certificate chain file. A certificate chain is a list of certificates that is sent by the server during the TLS handshake that allows the client to validate the identity of the server and ensure it is trusted. It consists of the certificate of the server, such as the certificate to be used to identify the edge device, followed by the intermediate CA certificate used to sign the server certificate. Certificate validation requires that root keys be distributed independently, so the 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.
Example 10. Certificate Chain Example

-----BEGIN CERTIFICATE-----
(Your EMS Server Certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(The Intermediate CA Certificate of the issuer of the EMS Server Certificate)
-----END CERTIFICATE-----
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 WS EMS and in config.lua for the Lua Script Resource. The following examples show what to add in both of these configuration files:
Example 11. config.json

"http_server": {
"certificate": "/path/to/certificate_chain/file"
}
Example 12. config.lua

scripts.script_resource_certificate_chain = "/path/to/certificate_chain/file"
Creating and Using a Custom Certificate Authority List
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. This list is commonly called a 'Certificate Authority List' or CA list. It should contain all root and intermediate certificates trusted by the edge device. This list allows the client to validate each node in the certificate chain presented by the server. Like the certificate and private key files, it should be PEM encoded. If you have certificate validation enabled, you must create and configure a Certificate Authority list. If you are using a self-signed certificate, you do not need to configure a CA list.
To create a Certificate Authority List, create a file that contains all the Certificate Authority certificates that you want you agent to trust. This file will typically contain the root and intermediate CA certificates that are used on the ThingWorx server with which the WS EMS communicates, as well as the root and intermediate CA certificates that were used to create the certificates used by the WS EMS and the LSR. Here is an example of a Certificate Authority List:

-----BEGIN CERTIFICATE-----
(Root CA Certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate CA Certificate)
-----END CERTIFICATE-----
Once you have created the CA List file, you need to specify the path to this file in the configuration files for the WS EMS and the Lua Script Resource, as shown in the following examples:
Example 13. config.json

"certificates": {
"cert_chain": "/path/to/ca_cert/file"
}
Example 14. config.lua

scripts.rap_cert_file = "/path/to/ca_cert/file"