Skip to main content

Configure TLS for a server

Configure a FairCom server to use a TLS server certificate

FairCom servers communicate over a variety of secure protocols, including HTTPS, MQTTS, MQTTWSS, WSS, SQL, and FairCom's proprietary protocol for its ISAM and CTDB APIs. This section describes how to enable secure TLS communications over all these protocols. The following steps must be performed on each FairCom server instance you wish to use TLS-encrypted connections. For more information on the keywords used here, visit the security page in our Database Administrator's Guide.

  • The web protocols (HTTPS, MQTTS, MQTTWSS, and WSS) are configured in the services.json configuration file.

  • FairCom's proprietary protocols (ISAM, CTDB, and SQL) are configured in the ctsrvr.cfg configuration file.

How to enable secure TLS communications over HTTPS, MQTTS, MQTTWSS, WSS, SQL, and FairCom's proprietary protocol for its ISAM and CTDB APIs

enable secure TLS communicationsTLS HTTPSTLS MQTTSTLS MQTTWSSTLS WSSTLS SQLsecure communicationISAM APICTDB API

Enable TLS for JSON APIs, MQTT, and browser-based apps (HTTPS, MQTTS, MQTTWSS, and WSS)

Note

Use the Google Chrome browser for FairCom browser-based tools. Other browsers may cause unexpected behavior.

FairCom servers include a built-in app server that supports FairCom’s JSON APIs, browser-based applications, and MQTT broker. The app server communicates over TCP/IP ports using HTTP/HTTPS, WebSocket, and MQTT protocols.

Enable and configure listeners for these ports and protocols in the services.json file. You must use different ports for TLS and non-TLS connections. For TLS connections, configure the "tls" property for a listener.

  1. Navigate to and open the services.json file in the <faircom>/config folder.

  2. This JSON file starts with an array called "listeners". Locate the object / block in that array that corresponds to the service you are interested in (following this table), and then proceed with the following steps, modifying the block which you selected:

    Protocol

    Object / block in "listeners" array

    HTTPS/WSS

    "serviceName": "https8443"

    MQTTS

    "serviceName": "mqtts8883"

    MQTTWSS

    "serviceName": "mqttwss9002"

  3. Use the "certificateFilename" property to specify the filename and optional path of the server certificate file on that server. (For info on creating a certificate file, see Create a server certificate and createservercert.py).

    Note

    You do not need to specify a path when the file is located in the <faircom>/server folder. If you use Windows path separators (\), please escape each one out with an extra \ (e.g. "C:\\my\\path\\serverCert.pem"). Use the "privateKeyFilename" property to specify the filename and optional path of the server key file.

  4. Use the "privateKeyFilename" property to specify the filename and optional path of the server key file.

    Note

    This property is optional. It is not needed if you embed the server key in the server certificate file mentioned in step 3.

  5. Optionally, use the "certificateAuthoritiesFilename" property to specify the filename and optional path of the CA certificate file to require clients to authenticate using X509 client certificates. If you choose to do this, a client certificate must be generated and distributed to each client.

  6. Verify that the files you specified above actually exist at the specified locations on this server computer.

  7. Optionally, use the "allowedCipherSuites" property to specify a list of cipher suites that you require clients to use.

  8. If your FairCom server is already running, restart it so the changes you have made to the services.json file take effect.  This file is processed only at server startup time.

Examples

Minimally secure TLS examples

"tls": { 
  "certificateFilename": "serverCert.pem", 
  "privateKeyFilename": "serverKey.pem"
}

"tls": { 
  "certificateFilename": "serverCertAndKey.pem" 
}

Secure TLS example with a wide variety of options

{ 
    "serviceName": "https8443", 
    "description": "Port 8443 using TLS-secured HTTPS protocol", 
    "port": 8443, 
    "protocol": "https", 
    "enabled": true,
    "tls": {
      "certificateFilename": "serverCert.pem",
      "privateKeyFilename": "serverKey.pem",
      "certificateAuthoritiesFilename": "caCert.pem",
      "allowedCipherSuites": [
        "TLS_AES_128_GCM_SHA256",
        "TLS_AES_256_GCM_SHA384",
        "TLS_CHACHA20_POLY1305_SHA256",
        "ECDHE-ECDSA-AES128-GCM-SHA256",
        "ECDHE-RSA-AES128-GCM-SHA256",
        "ECDHE-ECDSA-AES256-GCM-SHA384",
        "ECDHE-RSA-AES256-GCM-SHA384",
        "ECDHE-ECDSA-CHACHA20-POLY1305",
        "ECDHE-RSA-CHACHA20-POLY1305",
        "DHE-RSA-AES128-GCM-SHA256",
        "DHE-RSA-AES256-GCM-SHA384"
      ]
    }
}

Tip

You can run the nmap command line utility against FairCom's default app server port 8443 to verify the TLS ciphers in use. Linux includes nmap, and you can install nmap on Windows and MacOS.

nmap-p 8443 -v -Pn --script ssl-enum-ciphers localhost

Enable TLS for SQL, ISAM, and CTDB

  1. Navigate to and open the ctsrvr.cfg file in the <faircom>/config/ folder.

  2. Edit or add the SUBSYSTEM COMM_PROTOCOL SSL setting.

    Note

    The SUBSYSTEM COMM_PROTOCOL SSL setting normally exists in ctsrvr.cfg but is commented out with a semicolon at the beginning of the section. Uncomment it by removing the semicolon.

  3. If this setting does not exist, add it using the Default minimally secure configuration for COMM_PROTOCOL SSL example.

  4. Modify Default minimally secure configuration for COMM_PROTOCOL SSL example to match your desired TLS configuration options.

    Note

    The default setting is insecure because it is designed for maximum connectivity and compatibility while evaluating the server.

  5. Verify that the files you specified above actually exist at the specified locations on this server computer.

  6. Create and use a secure configuration for all your environments.

  7. If your FairCom server is already running, please restart it so the changes you have made to the ctsrvr.cfg file take effect.  This file is processed only at server startup time.

Examples

Default minimally secure configuration for COMM_PROTOCOL SSL example

SUBSYSTEM COMM_PROTOCOL SSL {
  SERVER_CERTIFICATE_FILE serverCert.pem
  SSL_CONNECTIONS_ONLY NO
  SSL_CIPHERS ALL:!aNULL:!eNULL:!SSLv2:!LOW:!EXP:!RC4:!MD5:@STRENGTH
}

Maximally secure configuration for COMM_PROTOCOL SSL example

SUBSYSTEM COMM_PROTOCOL SSL {
  SERVER_CERTIFICATE_FILE my_server_certificate.pem
  SERVER_PRIVATE_KEY_FILE my_server_key.key
  SSL_CONNECTIONS_ONLY YES
  SSL_CIPHERS AES256-SHA256:AES256-GCM-SHA384:DHE-RSA-AES256-SHA256
}

Enable TLS client certificates for MQTTS and MQTTWSS

  1. Ensure you have TLS configured as described in the Enable TLS for SQL, ISAM, and CTDB section.  Minimally you need to have the SERVER_CERTIFICATE_FILE property set to your server certificate.

    SERVER_CERTIFICATE_FILE /Certs/serverCert.pem

    Example

    SUBSYSTEM COMM_PROTOCOL SSL {
  SERVER_CERTIFICATE_FILE /Certs/serverCert.pem
  SSL_CONNECTIONS_ONLY YES
  VERIFY_CLIENT_CERTIFICATE YES
  x509_AUTHENTICATION YES
  x509_PATH CN
}

  2. Configure the TLS block of the protocol (MQTTS) to include the CA certificate and the server keypair.

    "tls": {
  "serverCertificateFilename": "/Certs/serverCert.pem",
  "certificateAuthoritiesFilename": "/Certs/ca.crt", 
  "clientCertificateFilename": "adminClient.pem"
}

  3. While still in services.json, ensure the authenticationMethods block in the mqtt section contains "clientCertificate".

  4. Start or restart the server.

Sample Python script to test the connection

import time

import paho.mqtt.client as mqtt


def message_callback( message_client, userdata, message ):
  print( message.payload.decode( 'utf-8' ) )


if __name__ == "__main__":
  topic = "test/IncrediblySimpleMqttsClientCertTopic"
  mqtts_client = mqtt.Client( client_id = "MQTTS secured client" )
  mqtts_client.tls_set( ca_certs = "/Certs/ca.crt",
                        certfile = "/Certs/AdminClient.pem",
                        keyfile = "/Certs/AdminClient.pem" )
  mqtts_client.on_message = message_callback
  mqtts_client.loop_start()

  mqtts_client.connect( "127.0.0.1", port = 8883 )
  time.sleep( 2 )

  mqtts_client.subscribe( topic )
  mqtts_client.publish( topic, "Incredibly Simple MQTTS client certificate message" )

  count = 0
  while count < 5:
    time.sleep( 1 )
    count += 1
  mqtts_client.unsubscribe( topic )
  mqtts_client.disconnect()
  mqtts_client.loop_stop()

Secure Hypertext Transfer Protocol (HTTP) is the HTTP protocol running over TLS. It provides secure request-response communications between computers.

Secure Message Queueing Telemetry Transport (MQTTS) is the MQTT protocol running over TLS. It provides secure messaging between computers.

Message Queueing Telemetry Transport over WebSocket Secure (MQTTWSS) is the MQTT protocol running over TLS and WebSocket. It provides secure messaging between computers. It is typically used by single-page browser applications.

WebSocket Secure (WSS)is the secure version of WebSocket. It uses TLS to create secure communications.

Structured Query Language (SQL) is a standardized programming language that is used to manage relational databases and perform various operations on the data in them.

FairCom's SQL engine is ANSI compliant and has almost all SQL features up through the SQL:2003 standard.

Indexed Sequential Access Method (ISAM) is FairCom's primary ACE API. ISAM uses the Record Buffer Method, which gives the application full control over the contents of the entire record buffer to store structured or unstructured data.

FairCom's ISAM API provides full control over record processing. This allows developers to implement data processing algorithms that are tailored to precise application needs, and this allows an application to achieve unrivaled performance. FairCom's ISAM API works best in the C and C++ languages.

FairCom ACE APIs include ISAM, CTDB, and Low-level ACE API.

The c-tree Database API (CTDB API) is FairCom's database API in the ACE family of APIs. It provides high performance with less code than the FairCom's ISAM API. The CTDB API introduces database concepts that are compatible with SQL. It requires records to contain predefined field structures. FairCom's CTDB API provides full control over record processing. This allows developers to implement data processing algorithms that are tailored to precise application needs, and this allows an application to achieve unrivaled performance. FairCom's CTDB API works well in a variety of languages, such as C, C++, Java, C#, and Visual Basic.

FairCom ACE APIs include ISAM, CTDB, and Low-level ACE API.