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.
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] (https://chocolatey.org/packages/OpenSSL.Light)) to install the “Light” version of OpenSSL.
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.
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:
geode.properties fileIn your code, using methods defined on the cacheFactory object
Set ssl-enabled to true.
Set ssl-truststore to point to your truststore file. This is needed for both one-way and two-way encryption.
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")
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.
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.
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.
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.
