SSL Client/Server Communication

This section describes how to configure OpenSSL, implement SSL-based communication between your clients and servers, and run clients and servers with SSL enabled.

Set Up OpenSSL

The open-source OpenSSL toolkit provides a full-strength general purpose cryptography library to operate along with the PKCS sample implementation for encrypted authentication of native client credentials.

Download and install OpenSSL 1.0.2 for your specific operating system. For Windows platforms, you can use either the regular or the “Light” version.

Note for Windows users: 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.

Step 1. Create keystores

The GemFire server requires keys and keystores in the Java Key Store (JKS) format while the native client requires them in the clear PEM format. Thus you need to be able to generate private/public keypairs in either format and convert between the two using the keytool utility and the openssl command.

There are public third party free tools and source code available to download such as the “KeyTool IUI” tool.

Step 2. Configure environment variables

Configure your system environment to build and run OpenSSL by adding the appropriate executable and library directories to your paths. For example, for Bourne and Korn shells (sh, ksh, bash), environment setup would look something like this: % LD_LIBRARY_PATH=$LD_LIBRARY_PATH:client-install-dir/lib:client-install-dir/ssl_libs:openssl-install-dir/lib
% export LD_LIBRARY_PATH
% CLASSPATH=server-install-dir/lib/securityImpl.jar:$CLASSPATH

where:

client-install-dir is the directory in which you installed your client.

openssl-install-dir is the directory in which you installed OpenSSL.

server-install-dir is the directory in which you installed your server.

For Windows, environment setup might resemble this: > set PATH=jdk-or-jre-path\bin;client-install-dir\bin;client-install-dir\ssl_libs;openssl-install-dir\bin;%PATH%
> set CLASSPATH=server-installdir\lib\securityImpl.jar;%CLASSPATH%

where jdk-or-jre-path is the directory in which Java is installed.

Step 3. Enable SSL on the server and on the client

  1. On the server, enable SSL for the locator and server components, as the SSL-enabled client must be able to communicate with both locator and server components. For details on the SSL properties available on the server, see “Managing > Security > SSL > Configuring SSL” in the GemFire User’s Guide.

  2. On the client, set ssl-enabled to true.

  3. On the client, set ssl-keystore and ssl-truststore to point to your keystore files. Paths to the keystore and truststore are local to the client. See Security-Related System Properties for a description of these properties.

Starting and stopping the client and server with SSL in place

Before you start and stop the client and server, make sure you configure the native client with the SSL properties as described and with the servers or locators specified as usual.

Specifically, ensure that:

  • OpenSSL and ACE_SSL DLLs locations are in the right environment variables for your system: PATH for Windows, and LD_LIBRARY_PATH for Unix.
  • You have generated the keys and keystores.
  • You have set the system properties.

For details on stopping and starting locators and cache servers with SSL, see Starting Up and Shutting Down Your System.

Example locator start command

Ensure that all required SSL properties are configured in your server’s gemfire.properties file. Then start your locator as follows:

gfsh>start locator --name=my_locator --port=12345 --dir=. \
--security-properties-file=/path/to/your/gemfire.properties

Example locator stop command

gfsh>stop locator --port=12345 \
--security-properties-file=/path/to/your/gemfire.properties

Example server start command

Again, ensure that all required SSL properties are configured in gemfire.properties. Then start the server with:

gfsh>start server --name=my_server --locators=hostname[12345] \
--cache-xml-file=server.xml --log-level=fine \
--security-properties-file=/path/to/your/gemfire.properties

Example server stop command

gfsh>stop server --name=my_server