Skip to main content

Use TLS to secure communications between FairCom DB Notify and FairCom MQ

To secure communications between FairCom DB Notify and FairCom MQ, update the dbnotifyconnections.json file with CA, server, and client certificates.

Use a TLS certificate for the server and each client

To secure a FairCom server with TLS, three files are needed:

  • A Certificate Authority (CA) file

  • A server key file

  • A server certificate file

Note

If all clients will be running on the same machine as the server, they can be configured to use the three files listed. To connect your clients to a TLS-secured server, three files for each client are needed:

  • A Certificate Authority (CA) file (this must be the same file used by the server)

  • A unique client key file

  • A unique client certificate file

To learn more about creating certificates, see Create TLS certificates.Tutorial: Create certificates using OpenSSL

Use the dbnotifyconnections.json file

The dbnotifyonnections.json file has a "brokerConnectionName" property set by default to "brokerCtree". This connection can be used, or a new one can be created.

Example 1. dbnotifyconnections.json file content
{
  "mqttBrokerConnections":
  [
    {
      "brokerConnectionName": "brokerCtreeTLS",
      "brokerHostname": "localhost",
      "brokerPort": 8883,
      "brokerUserName": "ADMIN",
      "brokerUserPassword": "ADMIN",
      "brokerPasswordEncryption": "none",
      "reconnectFrequencySeconds": 15,
      "tls": {
        "certificateAuthoritiesFilename": "C:/Certificates/ca.crt",
        "certificateFilename":            "C:/Certificates/server.crt",
        "privateKeyFilename":             "C:/Certificates/server.key"
      },
      "metadata": {}
    }
  ]
}


Update the dbnotifyconnections.json file

In Example 1, “dbnotifyconnections.json file content”, a connection named "brokerCtreeTLS" is used.

  1. Set the "brokerPort" property to a port that is appropriate for your network. 

    The most common port used for MQTTS is 8883.

    1. Set the "brokerHostname" property to the hostname or IP address of the MQTT broker that you wish to publish the database notifications to. 

      Note

      • This value must match the Common Name or Subject Alternate Name in the target server certificate. 

      • In Example 1, “dbnotifyconnections.json file content”, "localhost" is used as the "brokerHostname".  Doing this will require the server certificate to use a Common Name or Subject Alternate Name of "localhost".

    2. Query the server certificate by using:

      openssl x509 -text -in server.crt -noout

  2. Set the "brokerUserName" and "brokerUserPassword" properties to a valid username and password for the target broker. 

    Note

    If the broker has no username or password configured, these properties should be left blank.

  3. Edit the "tls" array to include three additional properties:

    • The "certificateAuthoritiesFilename" set to the Certificate Authority (CA) filename you are using.

    • The "privateKeyFilename" set to your server key filename.

    • The "certificateFilename" set to your server certificate filename.

  4. Encrypt the dbnotifyconnections.json file.

    • Rename dbnotifyconnections.json to dbnotifyconnections.cfg.

    • Execute “ctcmdset dbnotifyconnections.cfg” to get an encrypted dbnotifyconnections.set file.

    • Rename dbnotifyconnections.set to dbnotifyconnections.json.

  5. Start or restart the server and trigger a DB Notification event to test.