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.
Implementation
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:
CONNECTED(00000003) 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 -----BEGIN CERTIFICATE----- MIIFyzCCA7OgAwIBAgIUUf2qz00UayRbs5SLijNbsomQcikwDQYJKoZIhvcNAQEN BQAwdDELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAldBMRAwDgYDVQQHDAdTZWF0dGxl MRIwEAYDVQQKDAlSYWltYSBJbmMxEDAOBgNVBAMMB1N1cHBvcnQxIDAeBgkqhkiG 9w0BCQEWEXN1cHBvcnRAcmFpbWEuY29tMCAXDTI0MDEyNDAwMTY1MVoYDzIwNTEw NjExMDAxNjUxWjB0MQswCQYDVQQGEwJVUzELMAkGA1UECAwCV0ExEDAOBgNVBAcM ... J8KX3UfehUmu3nA5SFnl+e2CsBDGGorachbSfxitDLepoXCmwVNbyH0LixeAhhLK zE7w3K9GS4+a25CHzDcv7RKX2EF7+u0pxrzQTLch4e0rW9x7Wi7L0MIcgAmuiiJr zmbtHqIWkX7JuqiPxASA4h9nQB32UvlmDdKz4Vf4xn6wXnRO4XQiKDz2StX64Qhz /xV72aZXK77r1bGwUuM50YbM+iCp33z/OG2nBJvN+xdrP1XIX/+wa83i8boy0cc= -----END CERTIFICATE----- --- 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) ---