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 our Database Administrator's Guide.
- The web protocols (HTTPS, MQTTS, MQTTWSS, and WSS) are configured in the
services.jsonconfiguration file. - FairCom's proprietary protocols (ISAM, CTDB, and SQL) are configured in the
ctsrvr.cfgconfiguration file.
Enable TLS for JSON APIs, MQTT, and browser-based apps (HTTPS, MQTTS, MQTTWSS, and WSS)
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.
- Navigate to and open the services.json file in the
<faircom>/configfolder. - 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" |
- Use the
"certificateFilename"property to specify the full absolute filename of the server certificate file on that server. (For info on creating a certificate file, see Create a server certificate and createservercert.py).- If you use Windows path separators (\), escape each one out with an extra \ (e.g. "
C:\\my\\path\\serverCert.pem"). - If using relative paths, the path must be relative to the
<faircom>/serverfolder.
- If you use Windows path separators (\), escape each one out with an extra \ (e.g. "
- Use the
"privateKeyFilename"property to specify the absolute filename of the server key file.- This property is optional. It is not needed if you embed the server key in the server certificate file mentioned in step 3. Certificates created by createservercert.py include the key in the certificate file and should not specify a
privateKeyFilename.
- This property is optional. It is not needed if you embed the server key in the server certificate file mentioned in step 3. Certificates created by createservercert.py include the key in the certificate file and should not specify a
- Use the
"caCertificateFilename"property to specify the full absolute filename of the CA certificate file. This is mandatory if using client certificate authentication. - Verify that the files you specified above actually exist at the specified locations on this server computer. Verify that file permissions allow access to the private key only to the FairCom server process.
- Optionally, use the
"allowedCipherSuites"property to specify a list of cipher suites that you require clients to use. - If your FairCom server is already running, restart it so the changes you have made to the
services.jsonfile take effect. This file is processed only at server startup time.
Examples
Minimal TLS examples
"tls": {
"certificateFilename": "c:/programdata/faircom/edge/config/serverCertAndKey.pem"
}
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": "c:/my/certs/serverCert.pem",
"privateKeyFilename": "c:/my/certs/serverKey.pem",
"caCertificateFilename": "c:/my/certs/ca.crt",
"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"
]
}
}
You can run the
nmapcommand line utility against FairCom's default app server port 8443 to verify the TLS ciphers in use. Linux includesnmap, and you can installnmapon Windows and MacOS.
nmap-p 8443 -v -Pn --script ssl-enum-ciphers localhost
Enable TLS for SQL, ISAM, and CTDB
- Navigate to and open the
ctsrvr.cfgfile in the<faircom>/config/folder. - Edit or add the
SUBSYSTEM COMM_PROTOCOL SSLsetting.- The
SUBSYSTEM COMM_PROTOCOL SSLsetting normally exists inctsrvr.cfgbut is commented out with a semicolon at the beginning of the section. Uncomment it by removing the semicolon.
- The
- If this setting does not exist, add it using the Default minimally secure configuration for
COMM_PROTOCOL SSLexample below. - Modify Default minimally secure configuration for
COMM_PROTOCOL SSLexample to match your desired TLS configuration options. - Verify that the files you specified above actually exist at the specified locations on this server computer. Verify that files containing the server private key have filesystem permissions allowing access only to the server process.
- If your FairCom server is already running, please restart it so the changes you have made to the
ctsrvr.cfgfile take effect. This file is processed only at server startup time.
Examples
Default minimal configuration for COMM_PROTOCOL SSL example
SUBSYSTEM COMM_PROTOCOL SSL {
SERVER_CERTIFICATE_FILE c:/programdata/faircom/edge/config/serverCert.pem
SSL_CONNECTIONS_ONLY NO
}
Advanced configuration for COMM_PROTOCOL SSL example
SUBSYSTEM COMM_PROTOCOL SSL {
SERVER_CERTIFICATE_FILE c:/my/certs/my_server_certificate.pem
SERVER_PRIVATE_KEY_FILE c:/my/keys/my_server_key.pem
SSL_CONNECTIONS_ONLY YES
SSL_DEBUG_LOG c:/programdata/faircom/edge/data/ssl.log
SSL_CIPHERS TLS_AES_256_GCM_SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
}
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.pyscript creates a server certificate file that contains a server private key. - Put the full path of the server certificate's full absolute file name in this property.
- If you specify a relative path with the file name, the path will be relative to the
<faircom>/serverfolder. - If your company has a security team that manages certificates, you have additional options:
- A server private key can be in a separate file.
- The server certificate may be either self-signed or include a CA certificate following the server certificate.
SERVER_PRIVATE_KEY_FILE
SERVER_PRIVATE_KEY_FILE is an optional property that specifies the full name of a server key file:
- This property can be omitted if the server key is embedded in the server certificate file.
- FairCom's
createservercert.pyscript creates a server certificate with an enbedded server private key. - Put the absolute path to the server private key file in this property.
- If you specify a relative path with the server key file name, the path will be relative to the
<faircom>/serverfolder. - If your private key is encrypted, you must use the
SERVER_ENCRYPTED_STORE_FILEoption for the server to start.
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 an encrypted server key.
Essential information
- 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 optional.
- 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
ctcpvfutility 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_CONNECTIONS_ONLY
SSL_CONNECTION_ONLY is an optional property that specifies if a FairCom server requires all ISAM, CTDB, and SQL TCP communications to be encrypted using TLS (SSL), or if it accepts both encrypted and unencrypted communications. It defaults to NO.
Essential information
- It can be set to the value
NOorYES. - A value of
YESis the safest option because it requires all TCP communications to be encrypted. Shared memory is still allowed. - A value of
NOallows both encrypted and unencrypted TCP 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 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.