Use TLS with FairCom's ISAM, CTDB, and SQL client drivers

FairCom client driver settings to connect securely to FairCom's ISAM, CTDB, and SQL APIs

FairCom’s ISAM, SQL ODBC, and SQL JDBC client libraries require putting a server certificate file in the client process' working directory. This file must be a PEM file containing the CA certificate (or self-signed server certificate). By default, the file must be named ctsrvr.pem. 

Client software can use the following code to register a certificate other than ctsrvr.pem that FairCom's driver will use to validate the server's self-signed or CA certificate:

ctSetCommProtocolOption(ctCOMMOPT_FSSLTCP_SERVER_CERTIFICATE, "my server cert.pem");

If you want to establish TLS communications with a FairCom server but do not want to verify the server’s identity, use the following code to register an empty server certificate file name with FairCom’s client software. This approach is vulnerable to a man-in-the-middle attack.

ctSetCommProtocolOption(ctCOMMOPT_FSSLTCP_SERVER_CERTIFICATE, "");

If an error occurs when connecting using TLS, the connection attempt returns error 1104 (SSLCONN_ERR). 

For troubleshooting, client software can use the following code to enable TLS logging to the specified file name:

ctSetCommProtocolOption(ctCOMMOPT_FSSLTCP_DEBUG_LOG, "ssldebug.log"); 

Alternatively, you can also set the environment variable CTSSL_DEBUG_LOG to the name of the SSL debug log file. 

You can use TLS security keywords to modify TLS behavior on a FairCom server.

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.

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.

 
  1. If this setting does not exist, add it using the Default minimally secure configuration for COMM_PROTOCOL SSL example.
  2. Modify Default minimally secure configuration for COMM_PROTOCOL SSL example to match your desired TLS configuration options.

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

 
  1. Verify that the files you specified above actually exist at the specified locations on this server computer.
  2. Create and use a secure configuration for all your environments.
  3. 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
}

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.

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 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_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 NO or YES.
  • A value of YES is the safest option because it requires all TCP communications to be encrypted. Shared memory is still allowed.
  • A value of NO allows 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 ECDH-ECDSA-AES128-GCM-SHA256:DHE-RSA-AES128-SHA256.

Essential information

  • 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).
 
 

Examples
Minimally secure example only allowing clients to connect securely

The example only allows clients to connect securely.

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

Minimally secure example with the broadest support

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

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

Insecure example

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
 
 
 
 
secure communication encryption

Was this article helpful?

Give feedback about this article

Related Articles