TLS/SSL Encryption

This section describes how to implement TLS-based communication between your client and the server using OpenSSL. When configuring TLS/SSL security for your client, you may find it helpful to refer to the server documentation on SSL.

Set Up OpenSSL

The open-source OpenSSL toolkit provides a full-strength general purpose cryptography library for encrypting client-server communications.

Download and install OpenSSL 1.1.1 for your specific operating system.

Notes for Windows users:

  • For Windows platforms, you can use either the regular or the “Light” version of SSL.

  • Use a 64-bit implementation of OpenSSL.

  • If you use Cygwin, do not use the OpenSSL library that comes with Cygwin, which is built with cygwin.dll as a dependency. Instead, download a fresh copy from OpenSSL.

  • For many Windows applications, the most convenient way to install OpenSSL is to use choco (see chocolatey.org) to install the “Light” version of OpenSSL.

Server Prerequisites

SSL must be enabled on the cluster for both locator and server components, as the SSL-enabled client must be able to communicate with both locators and servers.

Enable SSL on the Client

SSL is configured by setting the appropriate properties in your application. See Security-Related System Properties for a description of these properties.

Properties can be set in two ways:

  • In a geode.properties file
  • In your code, using methods defined on the cacheFactory object
  1. Set ssl-enabled to true.

  2. Set ssl-truststore to point to your truststore file. This is needed for both one-way and two-way encryption.

  3. If your app uses two-way encryption, set ssl-keystore and ssl-keystore-password.

To enable SSL in your code, use the cacheFactory.set() method to specify the parameters and their values:

cacheFactory.set("ssl-truststore", "/etc/ssl/certs/ca-certificates.crt")
cacheFactory.set("ssl-enabled", "true")

Troubleshooting SSL Configuration

This section describes behavior you might see if no valid certificates are available with the client app. These observations apply when your app runs with a local cluster, but may not apply when pushing the app to a Cloud Cache environment.

  • Validate your keystores and truststores, that they are valid and correct and properly signed.

  • Validate that your configuration is indeed using one-way or two-way SSL.

  • Validate that your crypto library is compatible with the minimum OpenSSL version specified in the System Requirements.

One-way SSL Missing a Trust Store

If you enable debug level logging, you can expect to see a log line as follows:

Exception while querying locator: apache::geode::client::SslException: Failed to read SSL trust store.

If you enable a minimum of config level logging, you can check the configuration from the log and look for the following line:

ssl-keystore =

Check that the path is defined and correct, and that you have read permission for the file.

Two-way SSL Missing a Key Store

You can expect to see these messages written to standard error:

ACE_SSL (20468|140634593449728) error code: 336151570 - error:14094412:SSL routines:ssl3_read_bytes:sslv3 alert bad certificate
ACE_SSL (20468|140634593449728) error code: 336462231 - error:140E0197:SSL routines:SSL_shutdown:shutdown while in init

If you enable debug level logging, you can expect to see a log line as follows:

Exception while querying locator: apache::geode::client::GeodeIOException: TcpSslConn::connect failed with errno: 336462231: Unknown error 336462231

You will see repeated attempts to configure and establish a connection, and this error will repeat.

If you enable config level logging, at least, you can check the config from the log and look for the following line:

ssl-keystore =

Check that the path is defined and correct, and that you have read permission for the file.

Two-way SSL missing a trust store

If you enable debug level logging, you can expect to see a log line as follows:

Exception while querying locator: apache::geode::client::SslException: Failed to read SSL trust store.

You will see repeated attempts to configure and establish a connection, and this error will repeat.

If you enable config level logging, at least, you can check the config from the log and look for the following line:

ssl-truststore =

Check that the path is defined and correct, and that you have read permission for the file.