LATEST VERSION: 9.0.6 - CHANGELOG
Pivotal GemFire® Native Client v9.0

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.

Follow these instructions to download and install OpenSSL for your specific operating system.

The native client requires OpenSSL 1.0.1t or later. For Windows platforms, you can use either the regular or the OpenSSL 1.0.1t “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 as described in the following section.

Step 1. Download and install OpenSSL

To install OpenSSL:

  1. Download the OpenSSL archive from the OpenSSL web site.

  2. Extract the archive in a directory of your choice. For example:

    $ tar xvzf openssl-1.0.1u.tar.gz
    x openssl-1.0.1u/ACKNOWLEDGMENTS
    x openssl-1.0.1u/apps/
    x openssl-1.0.1u/apps/app_rand.c
    ...
    
  3. Look in the top-level directory of the source distribution to identify the installation instructions for your operating system:

    $ cd openssl-1.0.1u
    $ ls INSTALL*
    INSTALL        INSTALL.DJGPP      INSTALL.MacOS      INSTALL.NW        INSTALL.OS2
    INSTALL.VMS    INSTALL.W32        INSTALL.W64        INSTALL.WCE
    
  4. Build the OpenSSL library by following the instructions for your operating system.

Step 2. Create keystores

The Geode 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 3. Configure environment variables

Configure your system environment to build and run OpenSSL. Follow the environment setup that applies to your operating system.

Bourne and Korn shells (sh, ksh, bash)

% OPENSSL=parent-folder-for-openssl-binaries; export OPENSSL
% GFCPP=product-dir; export GFCPP
% LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$GFCPP/lib:$GFCPP/ssl_libs:$OPENSSL/lib
% export LD_LIBRARY_PATH
% CLASSPATH=$GEMFIRE/lib/gfSecurityImpl.jar:$CLASSPATH

Windows

> set GFCPP=product-dir
> set OPENSSL=path-to-installed-openssl
> set PATH=jdk-or-jre-path\bin;%GFCPP%\bin;%GFCPP%\ssl_libs;%OPENSSL%\bin;%PATH%
> set CLASSPATH=path-to-gemfire-installation\lib\gfSecurityImpl.jar;%CLASSPATH%

where path-to-installed-openssl is typically C:\OpenSSL>.

Step 4. Configure SSL properties in gfcpp.properties and gemfire.properties

Configure SSL properties.

  1. In gfcpp.properties, set ssl-enabled to true and set ssl-keystore and ssl-truststore to point to your keystore files. See Security-Related System Properties (gfcpp.properties) for a description of these properties.
  2. On each locator, enable SSL and set the following SSL properties in the locator’s gemfire.properties file:

    ssl-enabled-components=server,locator
    ssl-protocols=any
    ssl-ciphers=SSL_RSA_WITH_NULL_SHA
    

    Make sure your choice of cipher matches a cipher supported on the server.

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 gfsecurity.properties file. Then start your locator as follows:

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

Example locator stop command

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

Example server start command

Again, ensure that all required SSL properties are configured in gfsecurity.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/gfsecurity.properties

Example server stop command

gfsh>stop server --name=my_server