Certificate Fingerprint Validation for EMS and LSR
Starting with 5.4.8, the EMS includes a security feature called "certificate fingerprint validation" that allows you to restrict HTTPS communication to a known set of trusted HTTPS server endpoints at the Edge. While TLS certificate validation ensures that your edge device is talking to a server endpoint that uses a certificate issued by a trusted Certificate Authority (CA), certificate fingerprint validation ensures that your edge device is talking only to a subset of explicitly trusted server endpoints.
The trusted HTTPS server endpoints can be REST endpoints that are configured with auto_bind to access a ThingWorx Platform through the EMS. They cannot be a ThingWorx Platform. The auto_bind feature provides a way of letting the EMS talk to HTTPS servers at the Edge that you want to represent as Things in ThingWorx. When you configure auto_bind, you must supply a REST endpoint for the EMS to communicate with. If the ThingWorx Platform makes a request down to that device, the EMS makes an HTTPS connection to the HTTPS server defined in the auto_bind configuration.
 |
Use of certificate fingerprint validation requires that SSL/TLS is enabled and configured for the EMS and LSR.
|
The following sections explain certificate fingerprint validation, how to generate fingerprints, and how to add validation to the configuration files for the EMS and LSR. Click the title of a section to display its content. Click the title again to hide the content.
How Does Certificate Fingerprint Validation Work?
When an edge device communicates with a server using HTTPS, it first validates that the server’s certificate is issued by a Certificate Authority that is trusted. Next, it takes the SHA256 hash of the server’s certificate, referred to as the certificate fingerprint, and compares it against an internal list of trusted fingerprints. If the fingerprint is found in the list, the connection is allowed to proceed. If it is not found, the connection is terminated.
| | If you are upgrading from a previous release of EMS/LSR to v.5.4.10 and have already used fingerprint validation, be aware that you need to change the configuration files for your EMS and LSR to use fingerprint_allowlist instead of fingerprint_whitelist. An error is written to the console and log files (if enabled) saying that this change needs to be made if you do not change it after upgrading your EMS and LSR instances. The EMS and LSR will exit after writing this error message. |
This feature is disabled by default. To enable it, you must generate certificate fingerprints and then add the fingerprint_allowlist property and the fingerprints to the configuration file. If you do not want to use it, do not add the property to the configuration file, not even as a placeholder for future use. Adding the property without adding fingerprint strings renders the configuration file invalid. The EMS does not start as a result.
Is Certificate Fingerprint Validation Used for Secure WebSocket Connections?
No, Certificate fingerprint validation is not supported on Secure WebSocket Connections to the ThingWorx Platform. TLS certificate and host name validation are used to confirm that the platform server endpoint is trusted.
Generating Certificate Fingerprints
The instructions for generating certificate fingerprints in this section apply to both EMS and LSR.
You can use OpenSSL used to generate certificate fingerprint values for a given certificate using the following command:
openssl x509 -noout -fingerprint -sha256 -inform pem -in [certificate-file.crt]
Where [certificate-file.crt] is the path to your certificate. This command produces strings similar to the output below.
C:\OpenSSL-Win32\bin>openssl x509 -noout -fingerprint -sha256 -inform pem -in c:\test\cert.cer
SHA256 Fingerprint=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
Copy the fingerprint value that is printed to the console and place it into the EMS or LSR configuration file. Fingerprints can contain the characters 0-9, A-F, and :. The : character is optional and ignored when the value is read.
Using the example above, the fingerprint of the certificate to copy and place in your configuration file would be
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
Adding Certificate Fingerprints to the EMS Configuration File
To enable fingerprint validation, you must add the fingerprint_allowlist property to the certificates group in the config.json configuration file of the EMS. The fingerprint_allowlist must consist of an array of strings in which each string containing a certificate fingerprint. For example:
{
"certificates": {
. . .
"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:EF:EA:4B:22:92:45:BD:01:7E:92:52"
]
. . .
}
}
 | If you leave this property in the configuration file without any fingerprint strings, the config.json file is invalid, causing the EMS to exit when it attempts to read this configuration file. |
Adding Certificate Fingerprints to the LSR Configuration File
To enable fingerprint validation for the LSR, you must add the fingerprint_allowlist property to the certificates group in the config.lua configuration file of the LSR. The fingerprint_allowlist must consist of one or more strings, each string containing a certificate fingerprint. If multiple strings are used, separate them using a comma, as shown here:
-- Single fingerprint
scripts.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"
-- Multiple Fingerprints
scripts.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:EF:EA:4B:22:92:45:BD:01:7E:92:52"
| | If you leave this property in the configuration file without any fingerprint strings, the config.lua file is invalid, causing the LSR to stop when it attempts to read this configuration file. |