Skip to main content

Secure MQTT with certificates

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

This tutorial shows how to use CA, server, and client certificates to secure MQTT communications in FairCom Edge and FairCom MQ servers. Certificates are more secure than a username and password.

Prerequisites

Create a new user named user1

On the computer where you installed the FairCom server, launch a Windows CMD prompt or Linux command line shell, change to the<faircom>/tools folder, and run the following command:

FairCom MQ
sa_admin -aADMIN -pADMIN -f"" -sFCEDGEMQ -oua user1 -w pass1
FairCom Edge
sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oua user1 -w pass1

This command adds the user1 account to the server for subsequent use in this tutorial. If you want to add additional usernames, run the command again with new values for user1 and pass1. You do not need to add the admin account to the server because it is built-in.

Create certificate authority files

This tutorial uses the FairCom Certificate Manager to create certificates. Once you create your own private certificate authority (CA) files, you can use them to create server and client certificates.

  1. Launch a Windows CMD prompt or Linux command line shell, change to the <faircom>/tools/certman folder.

  2. Run the createcacert.py script and answer the prompts. For help, see the Easy section in the documentation.

    1. When prompted for your company name, enter your company's official name and press ENTER.

    2. When prompted for a directory to manage certificates, enter a folder name like C:\certs and press ENTER.

    3. When prompted for years, press ENTER to expire the CA certificate in 10 years.

    4. Press ENTER to create the CA certificate files.

      Screenshot of the CA certificate files in the MQTT Certificate Tutorial.

  3. Copy the ca.crt file just created into the <faircom>/server folder.

  4. Copy the ca.crt file into a certificate folder used by your client software. This Python MQTT tutorial is an example of client software using TLS and client certificates.

  5. Optionally use this OS Keystore tutorial to install the ca.crt file in each computer where you use the Google Chrome browser to run FairCom's browser-based applications.

Create server certificate files

A server certificate securely identifies your FairCom server to clients. It protects your MQTT clients from man-in-the-middle attacks.

  1. Before starting, gather the server's hostname, DNS names, and IP addresses.

  2. Use the command line shell you previously opened to the <faircom>/tools/certman folder.

  3. Run createservercert.py and answer the prompts. For help see the Easy section in the documentation.

    1. When prompted for the server hostname, you must enter the server's DNS name and press ENTER.

      • To determine the server's hostname, open a command prompt on the target server and use the command hostname to display the server's hostname.

      • This application uses the hostname as the first part of the certificate filename followed by Server.pem. It also adds it to the certificate in the Subject Common Name (CN).

      • In this example, the hostname is apollo and the server certificate filename is apolloServer.pem.

    2. When prompted for months, press ENTER to expire the certificate in 13 months or enter another value.

    3. When prompted for the server's IP Addresses and DNS names, you must enter an IP Address or a DNS name and press ENTER.

      • This information is required and must be correct or clients will reject the server certificate. If clients connect to the server using a hostname, you must include it in the certificate. Likewise, if clients connect to the server using an IP Address, you must include it in the certificate.

      • Each value you enter is stored in the certificate extension called Subject Alternative Name (SAN).

      • If the server is your local computer, you should enter 127.0.0.1 and localhost so clients can connect using either one.

      • You will be repeatedly prompted to enter another IP Address or DNS name.

      • Press ENTER to exit the prompt for more IP addresses and DNS names.

    4. When prompted for a country code, optionally enter the two-character abbreviation of your country, such as US , and press ENTER.

    5. When prompted for a state, optionally enter the abbreviation of your state, such as UT , and press ENTER.

    6. When prompted for a city, optionally enter the name of your city, such as Salt Lake City , and press ENTER.

    7. When prompted for a department, optionally enter the department that manages certificates, such as IT Security, and press ENTER.

    8. When prompted for an email, you must enter the email address of your security administrator and press ENTER.

    9. Press ENTER to create the server certificate.

      Screenshot of saving the apolloServer.pem file in the MQTT certificate tutorial.

  4. Copy the pem file just created into the <faircom>/server folder.

Create two client certificates

You need to create two client certificates: one for the user1 account you created earlier and another for the built-in admin account. To do so, you will run createclientcert.py twice with different information each time.

  1. Use the command line shell you previously opened to the <faircom>/tools/certman folder.

  2. Run createclientcert.py and answer the prompts. For help see the Easy section in the documentation.

    1. When prompted for the Common Name, enter user1 , which is the username of an account, and press ENTER.

    2. When prompted for the certificate passphrase, press ENTER to omit it.

    3. When prompted for months, press ENTER to expire the certificate in 13 months.

    4. When prompted for a filename containing IP addresses and DNS names, press ENTER twice to omit it.

    5. Press ENTER to create the client certificate.

      Screenshot of the user1Client files in the MQTT Certificate Tutorial.

  3. Again run createclientcert.py and answer the prompts.

    1. When prompted for the Common Name, enter admin , which is the username of the built-in admin account.

    2. When prompted for the certificate passphrase, press ENTER to omit it.

    3. When prompted for months, press ENTER to expire the certificate in 13 months.

    4. When prompted for a filename containing IP addresses and DNS names, press ENTER twice to omit it.

    5. Press ENTER to create the client certificate.

      Screenshot of the admin client certificate files in the MQTT Certificate Tutorial.

  4. Copy the user1Client.pem file to the computer running your MQTT client software.

  5. Copy the adminClient.pem file to the <faircom>/server folder.

    • This file secures internal MQTT connections inside the FairCom server.

Configure the FairCom server

You need to change two configuration files and restart the server to enable certificates and secure the server.

Update ctsrvr.cfg

Modify the the <faircom>/config/ctsrvr.cfg file as follows.

  1. Add a semicolon ; to the beginning of the line containing COMM_PROTOCOL FSHAREMM to turn off the shared memory protocol.

  2. Remove the semicolon ; from the beginning of the line containing SUBSYSTEM COMM_PROTOCOL SSL { to enable secure communications over TLS (SSL).

  3. Remove the semicolon ; from the beginning of the line containing SERVER_CERTIFICATE_FILE ctree_ssl.pem to enable the server certificate.

  4. Remove the semicolon ; from the beginning of the line containing x509_AUTHENTICATION YES to enable client certificates.

  5. Remove the semicolon ; from the beginning of the line containing x509_PATH CN to tell the server to use the Common Name (CN) for the username's location in the client certificate.

  6. Change the server certificate filename from ctree_ssl.pem to the filename of the server certificate you created.  It is the hostname of your server plus Server.pem, such as apolloServer.pem.

  7. Save your changes to ctsrvr.cfg.

Update services.json

Modify the <faircom>/config/services.json file as follows.

  1. Set the "enabled" property to false for the "http8080", "mqtt1883", and "mqttws9001" protocols in the "listeners" list. This step disables these insecure protocols.

  2. Do the following In the "tls" property of each secure listener: "https8443", "mqtts8883", and "mqttwss9002".

    1. Set "certificateFilename" to the name of the server certificate file, such as "apolloServer.pem".

  3. Do the following in the "tls" property of the listener: "mqtts8883".

    1. Set "certificateAuthoritiesFilename" to ca.crt, which is the name of the CA certificate file.

    2. Set the "clientCertificateFilename" to "adminClient.pem", which is the name of the admin client certificate file.

  4. In the "mqtt" object, change the "authenticationMethods" property to "authenticationMethods": [ "clientCertificate" ] to restrict MQTT authentication only to client certificates.

  5. Save your changes to services.json.

  6. Verify your changes are similar to the following excerpt from the services.json file. Do not replace the services.json file with the following.

    {
  "listeners": [
    {
      "serviceName": "http8080",
      "port": 8080,
      "protocol": "http",
      "enabled": false
    },
    {
      "serviceName": "https8443",
      "port": 8443,
      "protocol": "https",
      "enabled": true,
      "tls": {
        "certificateFilename": "apolloServer.pem"
      }
    },
    {
      "serviceName": "mqtt1883",
      "port": 1883,
      "protocol": "mqtt",
      "enabled": false
    },
    {
      "serviceName": "mqtts8883",
      "port": 8883,
      "protocol": "mqtts",
      "enabled": true,
      "tls": {
        "certificateFilename": "apolloServer.pem",
        "certificateAuthoritiesFilename": "ca.crt",
        "clientCertificateFilename": "adminClient.pem"
      }
    },
    {
      "serviceName": "mqttws9001",
      "port": 9001,
      "protocol": "mqttws",
      "enabled": false
    },
    {
      "serviceName": "mqttwss9002",
      "port": 9002,
      "protocol": "mqttwss",
      "enabled": true,
      "tls": {
        "certificateFilename": "apolloServer.pem"
      }
    }
  ],

  "mqtt": {
    "authenticationMethods": [ "clientCertificate" ]
  }

}

  7. Restart the FairCom server to apply the changes.

Configure MQTT client programs

A client application must connect to MQTT port 8883 to create a secure TLS connection with the broker. Connecting to MQTT port 1883 creates an insecure connection.

The following tutorials show how to use a client certificate to connect clients securely to MQTT: