Skip to main content

Securing FairCom's MQTT broker with client certificates

Tutorial to configure FairCom servers to use secure MQTT connections with CA, server, and client certificates

Client certificate requirements

  • The client certificate must be signed by the CA designated by listeners.[MQTTS listener].tls.caCertificateFilename in services.json.

  • The Common Name (CN) attribute of the client certificate must be set to a valid username in the FairCom broker.

FairCom broker requirements

  • A CA certificate must be designated for the listeners.[MQTTS listener].tls.caCertificateFilename block of services.json.

  • The services.json mqtt.authenticationMethods array must contain "clientCertificate".

    If this array contains other authentication methods, clients can also authenticate using those methods.

    We recommend removing the "none" option when using client certificates.

Steps

  1. Create a client certificate with a CN that matches an existing username and is signed by the CA we designate in services.json.

  2. In services.json, configure the MQTTS listener caCertificateFilename property to the CA that signed the client certificates.

  3. In services.json, configure the MQTTS listener serverCertificateFilename property to a server certificate signed by the same CA.

  4. In services.json, set the "requireClientCertificate" property to "true" for the MQTTS listener.

  5. In services.json, remove the "none" option from the mqtt.authenticationMethods section.

  6. In ctsrvr.cfg add a semicolon to the COMM_PROTOCOL FSHAREMM line to comment it out.  It should look like this: ;COMM_PROTOCOL FSHAREMM

  7. In ctsrvr.cfg add (or modify) the following lines:

    ;Here is where you can activate (un-comment) SSL
SUBSYSTEM COMM_PROTOCOL SSL {
   ;This is the file name in your server's directory.
   SERVER_CERTIFICATE_FILE ./web/fccert.pem

   ;For SSL you can specify (un-comment) a debug log file name.
   DEBUG_LOG ssl.log

   ;Here you can restrict access to SSL ONLY.
   SSL_CONNECTIONS_ONLY YES

   ;Require clients to provide a x509 certificate.
   VERIFY_CLIENT_CERTIFICATE YES

   ;Use x509 client certificate for database authentication.
   x509_AUTHENTICATION YES

   ;Use the SUBJECT:CN from the client's certificate as their user name.
   x509_PATH CN

   ;Set the ciphers that will be allowed.
   SSL_CIPHERS AES256-SHA256:AES256-GCM-SHA38:DHE-RSA-AES256-SHA256:AES256-GCM-SHA384
}

    Note that the file specified by SERVER_CERTIFICATE_FILE is the same file specified in step 3 above.  This file is typically kept in the <FairCom installation>/server/web/ directory. Once those changes have been made, you should start or restart the server.

  8. Confirm certificates are working using the client of your choice, or by running the following Python script:

    import time
import paho.mqtt.client as mqtt


mqtts_client = mqtt.Client( client_id = "MQTTS client certs" )
mqtts_client.tls_set( ca_certs = "/FairCom/ca.crt",
                      certfile = "/FairCom/ClientAdmin.crt",
                      keyfile = "/FairCom/ClientAdmin.key" )
mqtts_client.loop_start()
mqtts_client.connect( "127.0.0.1", port = 8883 )
time.sleep( 2 )
mqtts_client.publish( "test/SimpleMqttsClientCert", "Simple test message" )
mqtts_client.disconnect()
mqtts_client.loop_stop()

    Note that the value in the time.sleep( 2 ) line may need to be adjusted for your environment.