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) 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.