Enable client certificate authentication on a server

Enable client certificate authentication on a FairCom server

This section details how to enable client certificate authentication on a faircom server. For more information on the configuration options used here, visit the security section in our Faircom DB configuration options. For other security terminology, see Security terms.

  1. Create a server certificate (using createservercert.py), signed by a CA certificate and named something like ServerCertAndKey.pem
  2. ServerCertAndKey.pem contains the following data in this order:
    • Unencrypted Server private key
    • Server certificate
    • CA certificate
  3. Copy ServerCertAndKey.pem to a suitable location on the server.  We will use <faircom>/config/ServerCertAndKey.pem. Ensure that the filesystem permissions prevent users other than the faircom process from accessing this file, as it contains a private key.
  4. Edit FairCom's server configuration file, <faircom>/config/ctsrvr.cfg.
  5. Update the SUBSYSTEM COMM_PROTOCOL SSL section with the following minimal configuration:
SUBSYSTEM COMM_PROTOCOL SSL {
;This is the file name in your server's config directory
SERVER_CERTIFICATE_FILE c:/programdata/faircom/edge/config/ServerCertAndKey.pem
;For TLS troubleshooting, you can specify a debug log file name
;DEBUG_LOG c:/programdata/faircom/edge/data/ssl.log
;Allow x509 client certificates for database authentication
x509_AUTHENTICATION YES
;Use the SUBJECT:CN from the client's certificate as their user name
x509_PATH CN
}
  1. To enable TLS client certificates for HTTPS, MQTTS or MQTTWSS edit: <faircom>/config/services.json
  2. Update the listeners.tls section for HTTPS, MQTTS and/or MQTTWSS to include
                "tls": {
                        "serverCertificateFilename":"c:/programdata/faircom/edge/config/ServerCertAndKey.pem",
                        "caCertificateFilename":"c:/programdata/faircom/edge/config/ca.crt",
                        "requireClientCertificate": true
                }
                     The ca.crt specified in "caCertificateFilename" contains only the CA certificate.
  1. While still in services.json, ensure the authenticationMethods block in the mqtt section contains “clientCertificate”.
  2. Restart the FairCom server.