Product Documentation

Database Administrator's Guide

Previous Topic

Next Topic

Transport Layer Security Secures Data in Transit between Network FairCom DB Clients and Servers

Note: FairCom DB File and User Security are available only when using the client/server operational model.

FairCom applications can now secure data in transit between c-tree network clients and FairCom servers. Transport Layer Security (TLS, also commonly referred to as its predecessor SSL, Secure Sockets Layer) is a cryptographic protocol designed for secure network communications using public key cryptography for authentication of the communicating party. Symmetric cryptography is used to encrypt transmitted data over the wire. FairCom DB TLS relies on OpenSSL toolkit support and implements TLS protocol V1.3. Earlier versions of TLS (and predecessor SSL) protocols contain known and exploited vulnerabilities. FairCom DB only supports TLS via TCP/IP communications protocols (IPv4 and IPv6). (For more about TLS, see

Two modes of TLS connections are available: basic and peer authenticated. Basic TLS connections are encrypted using only a server-side certificate; there is no local certificate requirement for a client. This makes deployment and management of secured connections easy.

TLS Certificates

It is the server administrator’s responsibility to ensure a correct and valid certificate pair, as well as proper configuration of allowed TLS connections.

Creation and management of TLS certificates, as well as use of a Certification Authority (CA), is beyond the scope of this document. Consult OpenSSL and other TLS supporting documentation and be sure you firmly grasp all details regarding use of TLS for network security before deploying.

Server certificates may be created and provided as two separate files: a certificate and a key. They can also be combined into a single file. There is no required file naming convention. Certificate files are usually created and/or provided as Base64 encoded X.509 certificate files and denoted with a .pem extension (Privacy Enhanced Mail). They can be identified with this set of surrounding identifiers within the file:



The private key is likewise identified:



The private key is often included in the same certificate file or as a separate .key file.

A certificate key can be optionally passphrase protected. However, this then requires the passphrase to be presented at server startup. FairCom key store files provide this ability.

Always securely maintain key files. Store key files only in permissions protected server areas and never distribute.

Server-Side Configuration

To enable TLS (SSL), see keywords for TLS.

Standard c-tree TCP/IP ports are used for connections regardless of TLS configuration. That is, a single ISAM port will handle both TLS encrypted and non-encrypted connections, and likewise for the SQL port. There is no need for separate port configurations.

For the HTTPD plugin you can verify ciphers in use using the system nmap command (Linux) against the HTTPD port when no ciphers are specified in cthttpd.json. This can be done with the linux command:

nmap --script ssl-enum-ciphers -Pn -p 8443

Client-Side Configuration

Both FairCom ISAM and SQL clients support TLS connections.

Peer Authentication - TLS connection with server certificate validation:

By default, a c-tree client requires a PEM file containing the server public certificate—ONLY the public certificate, not the server private key.

Important: The server private key should be securely maintained only at the FairCom Server location at all times.

By default, ISAM and SQL client libraries use the file ctsrvr.pem in the client process' working directory when connecting. An ISAM client can change the file name that the client library searches for by calling the ctSetCommProtocolOption() function with the option ctCOMMOPT_FSSLTCP_SERVER_CERTIFICATE:

ctSetCommProtocolOption(ctCOMMOPT_FSSLTCP_SERVER_CERTIFICATE, "myservercert.pem");

Basic - TLS connection without server certificate validation (ISAM only):

It is also possible to establish a TLS connection from an ISAM client without validating the FairCom certificate. Such a connection is encrypted but there is no guarantee of the server’s identity. To use this option, call the ctSetCommProtocolOption() function with the option ctCOMMOPT_FSSLTCP_SERVER_CERTIFICATE with an empty certificate name before connecting:


When the client does not use a server certificate, the connection is encrypted, but there is no guarantee that the client is connected to that specific server. This implies that a "man in the middle" attack could be possible.

If an error occurs when connecting using SSL, the connection attempt returns error 1104 (SSLCONN_ERR). To get more detailed information enable SSL logging by either:

  • calling ctSetCommProtocolOption() with the ctCOMMOPT_FSSLTCP_DEBUG_LOG option:

ctSetCommProtocolOption(ctCOMMOPT_FSSLTCP_DEBUG_LOG, "ssldebug.log");


  • setting the environment variable CTSSL_DEBUG_LOG to the name of the SSL debug log file.

To request a TLS-enabled ISAM connection, append ^fssltcp to the server name. For example:

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

Note: When you append ^fssltcp to the server name you must quote the entire connection string, for example:


Windows normally interprets the carat as an escape character or line continuation, so the entire server connection string must be quoted when it includes a caret.

Other examples showing how to specify a desired communication protocol when connecting:

To connect using shared memory (without falling back to TCP/IP if the shared memory connection fails):


To connect using TCP/IP v4 without SSL:


To connect using TCP/IP v6 without SSL:


To connect using TCP/IP v6 with SSL:


To request a TLS-enabled connection for a SQL connection, prepend ssl: to the connection string. For example:

isql -u admin -p ADMIN ssl:6597@localhost:ctreesql

Standard FairCom DB SQL interfaces (JDBC, ADO.NET, ODBC, PHP, Python) each have independent standards for connection strings. JDBC and ADO.NET are specifically described later in this chapter.

ctadmn and FairCom DB Monitor show the communication protocol that is in use, including whether or not the connection is using TLS (SSL):

F_TCPIP indicates an unencrypted ISAM TCP/IP connection.

FSSLTCP indicates an SSL-enabled ISAM TCP/IP connection.

SQL_TCPIP indicates an unencrypted SQL TCP/IP connection.

SQL_SSLTCP indicates an SSL-enabled ISAM TCP/IP connection.

X.509 Support

Support has been added for X.509 client/server authentication. For now, only X.509 authentication when using TLS-encrypted TCP/IP for ctree is supported. Future revisions will extend this to SQL and shared memory protocols.

X.509 authentication is not supported in combination with LDAP authentication.

To use X.509 authentication, the client must provide a PEM formatted X.509 certificate with a complete certificate chain using the same root CA as the server certificate. If the client's certificate is successfully validated by the server, the subject field on the client X.509 will be parsed by the server to extract a username. This username is used to determine the database permissions to be granted. A complete certificate chain consists of a PEM formatted file with the certificate for the user, followed by the certificate for the issuer, followed by the certificate for that issuer, and so on, ending in the root CA certificate.

When X.509 authentication is enabled and a certificate is provided by the client, the username and password arguments passed to InitISAMX() are ignored.

New Security keywords have been added to enable X.509. See Client Communications Keywords for TLS.

The following functions have been enhanced for configuring X.509 authentication

  • ctSetCommProtocolOption
  • InitISAMXtd

Expected TLS Performance

The resource-intensive portion of a TLS connection is the initial creation. A secure communications channel is established via asymmetric encryption requiring a session key exchange. This initial key exchange and encryption process is the slowest computational epoch. Once connected, ongoing connection overhead is negligible. Further, most modern hardware contains dedicated CPU instructions for enhanced encryption performance. Thus, it is important to avoid repeated connections and maintain an established TLS connection when at all possible.



Advanced SSL Certificate Options

The ssl_certificate keyword in the config/cthttpd.json web server plug-in configuration supports the fccert.pem, which is a self-signed certificate we supplied. To use your own certificate, use the following keywords to config/cthttpd.json:

  • ssl_key: SSL private key - This can be embedded in the same file provided the in ssl_certificate. For example, our default fccert.pem certificate file has both the certificate and the private key, so, ssl_key is not required.
  • ssl_ca: SSL Certificate Authority - External authority that issues and validates the certificate.
  • ssl_cipher_suites - Colon-delimited list of SSL cipher suites.


There is a client-side environment variable for debugging. To enable SSL logging for the client, set the CTSSL_DEBUG_LOG environment variable to the log file name.

For server side SSL debugging, add DEBUG_LOG <logfile> to the SSL subsection.

In This Section

Testing with Default FairCom DB Certificates

ADO.NET Support for TLS

ODBC Support for SSL

JDBC Support for TLS

Allow ISAM Client to Use SSL without Client Having Server Certificate

OpenSSL Headers for Linking FairCom DB Client Applications

OpenSSL Now Provides Default Faster AES Encryption

TLS/SSL Tutorials