Use TLS with FairCom's ISAM and CTDB client drivers

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

Set up a CA Certificate

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

ISAM/CTDB client software can use the following code to register a certificate filename 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, "");

See other TLS/SSL related options available with ctSetCommProtocolOption. 

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

Make a TLS connection

To use a TLS-enabled ISAM connection, append ^fssltcp to the server name in the ISAM connection string, such as "FAIRCOMS@localhost^fssltp". You must put the connection string in quotes because Microsoft Windows interprets the carat as an escape character or line continuation.

The following example uses TLS to connect the ctadmn utility to a FairCom server named FAIRCOMS:

ctadmn ADMIN ADMIN "" “FAIRCOMS@localhost^fssltcp”

Troubleshooting

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

For troubleshooting, client software can set the environment variable CTSSL_DEBUG_LOG to the name of a TLS debug log file. 

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.
    1. 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.
    1. The default setting is insecure because it is designed for maximum connectivity and compatibility while evaluating the server.
  3. Verify that the files you specified above actually exist at the specified locations on this server computer.
  4. Create and use a secure configuration for all your environments.
  5. 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.