Configure a server to use a certificate

Configure a FairCom server to use a server certificate

Abstract

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. For more information on the keywords used here, visit the security page in our Database Administrator's Guide.

Note

On ISAM and SQL ports, a single TCP/IP port handles both TLS encrypted and unencrypted connections.

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.

Enable TLS for HTTPS, MQTTS, MQTTWSS, and WSS

Navigate to and open the services.json file in the <faircom>/config folder.
Use the "certificateFilename" property to specify the filename and optional path of the server certificate file.
Note
You do not need to specify a path when the file is located in the <faircom>/server folder.
Use the "privateKeyFilename" property to specify the filename and optional path of the server key file.
Note
This property is optional if you embedded the server key in the server certificate file.
Optionally, use the "certificateAuthoritiesFilename" property to specify the filename and optional path of the CA certificate file to allow clients to authenticate using X509 client certificates.
Optionally, use the "allowedCipherSuites" property to specify a list of cipher suites that you require clients to use.

Examples

Minimally secure TLS example

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

TLS example with a wide variety of options

"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"
  ]
}

Enable TLS for SQL, ISAM, and CTDB

Navigate to and open the ctsrvr.cfg file in the <faircom>/config folder.
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 (comment out a setting by placing a semicolon at the beginning of the section and uncomment by removing the semicolon).
If this setting does not exist, add it using the Default minimally secure configuration for COMM_PROTOCOL SSL example.
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.
Create and use a secure configuration for all your environments.

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 serverCert.pem
  SERVER_PRIVATE_KEY_FILE serverKey.pem
  SSL_CONNECTIONS_ONLY YES
  SSL_CIPHERS AES256-SHA256:AES256-GCM-SHA384:DHE-RSA-AES256-SHA256
}

SERVER_CERTIFICATE_FILE

SERVER_CERTIFICATE_FILE is a required property that specifies the name and optional path of a server certificate file.

A server certificate file is a PEM-encoded certificate that you create specifically for one server. It contains information that uniquely identifies the server, such as its host-name or IP addresses.
FairCom's createservercert.py script creates a server certificate file as well as a server key file.
The server certificate file is put in the <faircom>/server folder.
Put the server certificate file name in this property
If you specify a path with the file name, the path will be relative to the <faircom>/server folder.
If your company has a security team that manages certificates, you have additional options.
- A server certificate file may optionally embed the server key inside it.
- The server certificate may be self-signed.

SERVER_PRIVATE_KEY_FILE

SERVER_PRIVATE_KEY_FILE is an optional property (but is typically used) that specifies the name and optional path of a server key file.

This property can be omitted if the server key is embedded in the server certificate file.
FairCom's createservercert.py script creates a server certificate file as well as a server key file.
Put the server key file name in this property.
If you specify a path with the server key file name, the path will be relative to the <faircom>/server folder.

SERVER_ENCRYPTED_STORE_FILE

SERVER_ENCRYPTED_STORE_FILE is an optional property that specifies the name and optional path of an encrypted key store file, which contains a password that can decrypt a server key.

It is desirable, but not required, to encrypt a server key because it makes it more difficult for malicious users to steal the server key and impersonate the server.
Encrypting the server key complicates setting up security. For this reason, FairCom's scripts make key encryption optionsl.
The FairCom server needs to read the server key so it can use the server certificate to encrypt communications. When the server key is encrypted, the FairCom server cannot read the server key. The solution to this is to use FairCom's ctcpvf utility to create an encrypted key store file that contains the password for the server key. Only the FairCom server knows how to read the key store file and decrypt the password that it contains. This allows the FairCom server to retrieve the password and decrypt the server key. Once the FairCom server has the server key, it can use the server key with the server certificate to do encrypted TLS communications.

SSL_CIPHERS

SSL_CIPHERS is an optional property that specifies the encryption ciphers that are allowed to be used for encrypting a TLS (SSL) connection. It defaults to ECDH-ECDSA-AES128-GCM-SHA256:DHE-RSA-AES128-SHA256.

The default setting is considered secure by 2024 standards. The default value is a best practice because it requires clients to use full AES 256-bit encryption when they talk to the server.
A client is allowed to connect to the server only if it uses one of the ciphers in this list.
If a client cannot support AES 256-bit encryption, you need to add a lower encryption level to the list. This is undesirable because malicious users will attempt to connect at the lowest possible level so they can harm the system.
Each cipher is separated by a colon.
Adding @STRENGTH to the end of the list forces the server to prioritize the strongest algorithms first.
Place an exclamation point before a cipher to disable it (for more information, see the ciphers main page at OPENSSL.org).

The example only allows clients to connect securely.

AES256-SHA256:AES256-GCM-SHA384:DHE-RSA-AES256-SHA256

This example shows the minimally secure example with broadest client support.

!aNULL:!eNULL:!SSLv2:!LOW:!EXP:!RC4:!MD5:@STRENGTH

This example is insecure and allows clients to connect using any level of security from none to the maximal.

ALL:!aNULL:!eNULL:!SSLv2:!LOW:!EXP:!RC4:!MD5:@STRENGTH

Enable TLS client certificates for MQTTS and MQTTWSS

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
}
```

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"
}

While still in services.json, ensure the authenticationMethods block in the mqtt section contains "clientCertificate".
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()

Configure a server to use a certificate

Configure a FairCom server to use a server certificate

Note

Enable TLS for HTTPS, MQTTS, MQTTWSS, and WSS

Note

Note

Examples

Minimally secure TLS example

TLS example with a wide variety of options

Enable TLS for SQL, ISAM, and CTDB

Note

Note

Examples

Default minimally secure configuration for COMM_PROTOCOL SSL example

Maximally secure configuration for COMM_PROTOCOL SSL example

Enable TLS client certificates for MQTTS and MQTTWSS

Default minimally secure configuration for `COMM_PROTOCOL SSL` example

Maximally secure configuration for `COMM_PROTOCOL SSL` example