Tutorial: Configure a FairCom server to use a 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.
Note
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.
Navigate to and open the services.json file in the
<FairComInstallationFolder>/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
<FairComInstallationFolder>/server
folder.Use the
"privateKeyFilename"
property to specify the filename and optional path of the server key file.Note
You do not need to specify a path when the file is located in the
<FairComInstallationFolder>/server
folder.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": "cert.pem", "privateKeyFilename": "key.pem" }
Insecure TLS example with a wide variety of options
"tls": { "certificateFilename": "cert.pem", "privateKeyFilename": "key.pem", "certificateAuthoritiesFilename": "ca.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" ] }
Navigate to and open the
ctsrvr.cfg
file in the<FairComInstallationFolder>/config
folder.Edit or add the
SUBSYSTEM COMM_PROTOCOL SSL
setting.Note
The
SUBSYSTEM COMM_PROTOCOL SSL
setting normally exists inctsrvr.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 ctree_ssl.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_company_CA_certificate.pem SERVER_PRIVATE_KEY_FILE my_company_CA_key.key SSL_CONNECTIONS_ONLY YES SSL_CIPHERS AES256-SHA256:AES256-GCM-SHA38:DHE-RSA-AES256-SHA256 }