SSL (Secure Sockets Layer) Encryption

The RaimaDB SSL package includes the capability of communication using SSL between the clients and the TFS.  This section will provide an overview on how the developer can incorporate this feature into their application.


RaimaDB uses the OpenSSL libraries from the OpenSSL Project to implement encryption. Mechanisms to provide the TFS (listening server) with the private key and associated certificate to be used for the encryption. On the client side, the additional function is: rdm_dbGetCertificate() which is used to retrieve the certificate from the server.

RaimaDB WILL NOT validate that the certificate can be trusted, the developer will need to add their own code to validate the certificate received.

The TFS listening server can communicate with SSL clients and non-SSL clients. The listening server can be instructed to listen for SSL clients ONLY.

The client chooses if the communication will be SSL or not. RaimaDB will not default to using SSL if non-SSL is not available.

Private Keys and Certificates

The private keys and certificates used by RaimaDB are always in the PEM format, base64 encoded. These can be issued by any Certificate Authority (CA).  For testing purposes, a self-signed SSL certificate can be used.

If a private key and certificate is not provided, an internal, self-signed certificate will be used by default. The use of this default certificate is for testing only and your product should not be deployed using this default certificate.

Example SSL Usage

The following examples use artifacts from the core39Example and core40Example which are included in the installation package.

If you receive an eNOTIMPLEMENTED_TRANSPORT_SSL return code, the package you are using does not contain SSL capabilities. Please contact Sales at [email protected] to obtain this package.

TFS with SSL Support Using rdm-tfs

The rdm-tfs utility provides the central server capabilities for the RaimaDB clients to connect to a centralized database. By default, the TFS will be listening for SSL and non-SSL connections. For example:

$ rdm-tfs --docroot=/RaimaDB/datastore --privatekey-file=/RaimaDB/privatekey.pem --certificate-file=/RaimaDB/certificate.pem

The above command line starts the TFS using the /RaimaDB/datastore directory as the storage directory for all database images managed by this TFS. The privatekey.pem and certificate.pem files are the private key and certificate files provided by the Certificate Authority. Since we did not provide a transport name or port for this server, the default name and port will be: 21553.

For the following example, the --privatekey-file and --certificate-file arguments are not required. If they are eliminated, the default self-signed certificate in the rdm-tfs utility will be used.

With the above server running, we can connect to it using the core39Example program. This example program will set an option on the database handle prior to the database open that indicates that the transport must use SSL encryption to connect to the above TFS.

If we would have eliminated the call to rdm_dbSetOption() in this example, the connection would have succeeded but the connection would not be using SSL encryption. The use of SSL encryption is dictated by the connection options on the client.

If we stop the rdm-tfs TFS instance:

$ rdm-tfs --stop

And restart it with an additional argument (--force-ssl), the server will now only listen for SSL encrypted connections and reject non-SSL connections. The core39Example application program mentioned above will still connect to the server because we have set the use_ssl option to true. If the option was set to false (default), the connection to the TFS will fail.

To stop the rdm-tfs TFS instance when --force-ssl has been used:

$ rdm-tfs --stop --force-ssl

TFS with SSL Support Using a Custom TFS Application

The core40Example example demonstrates the functions needed to start a custom TFS with the certificate and private key embedded in the application. The application will setup a listening server within the process that other external clients (as well as the in-process clients) can connect.

In this example, the program will listen for SSL connections only:

If this option is not set, the TFS will listen for SSL and non-SSL connections.

Setting the Private Key and Certificate

For this example, we have placed the private key and certificate contents into the privatekey.h and certificate.h header files. For your example, you will place those content for the private key and certificate files per your application requirements. When the contents of those files are read into your application, the contents must be placed in buffers that are available for the duration of the TFS instance running.

The rdm_tfsSetCertificate() and rdm_tfsSetKey() functions will be used to register those buffer locations with the TFS instance to be instantiated:

Connecting to TFS Using SSL

In both the core39Example and core40Example programs, the connection using SSL is established and the programs retrieve the server's SSL certificate.

RaimaDB does not provide any validation of the certificate. It does provide the ability for the client to retrieve the SSL certificate (from the server) in use so that you can add certificate validation on the client side. However, if both the client and the server is provided by you, the validation could be hard coded into the client by simply doing a string compare.

For the rdm-tfs example above, we can view the certificate details using the openssl command (see OpenSSL Project).

$ openssl s_client -showcerts -connect localhost:21553

The above command assumes that the rdm-tfs is running on the same machine and is using the default 21553 port. For the default self-signed certificate, you will see the following output:

Can't use SSL_get_servername
depth=0 C = US, ST = WA, L = Seattle, O = Raima Inc, CN = Support, emailAddress = [email protected]
verify error:num=18:self-signed certificate
verify return:1
depth=0 C = US, ST = WA, L = Seattle, O = Raima Inc, CN = Support, emailAddress = [email protected]
verify return:1
Certificate chain
 0 s:C = US, ST = WA, L = Seattle, O = Raima Inc, CN = Support, emailAddress = [email protected]
   i:C = US, ST = WA, L = Seattle, O = Raima Inc, CN = Support, emailAddress = [email protected]
   a:PKEY: rsaEncryption, 4096 (bit); sigalg: RSA-SHA512
   v:NotBefore: Jan 24 00:16:51 2024 GMT; NotAfter: Jun 11 00:16:51 2051 GMT
Server certificate
subject=C = US, ST = WA, L = Seattle, O = Raima Inc, CN = Support, emailAddress = [email protected]
issuer=C = US, ST = WA, L = Seattle, O = Raima Inc, CN = Support, emailAddress = [email protected]
No client certificate CA names sent
Peer signing digest: SHA256
Peer signature type: RSA-PSS
Server Temp Key: X25519, 253 bits
SSL handshake has read 2299 bytes and written 373 bytes
Verification error: self-signed certificate
New, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384
Server public key is 4096 bit
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
Early data was not sent
Verify return code: 18 (self-signed certificate)