Apache Geode CHANGELOG

Configuring SSL

You can configure SSL for authentication between members and to protect your data during distribution. You can use SSL alone or in conjunction with the other Geode security options.

Geode SSL connections use the Java Secure Sockets Extension (JSSE) package, so the properties described here apply to Geode servers and to Java-based clients. SSL configuration in non-Java clients may differ — see the client’s documentation for details.

SSL-Configurable Components

You can specify that SSL be used system-wide, or you can independently configure SSL for specific system components. The following list shows the system components that can be separately configured to communicate using SSL, and the kind of communications to which each component name refers:

cluster

Peer-to-peer communications among members of a cluster

gateway

Communication across WAN gateways from one site to another

web

All web-based services hosted on the configured server, which can include the Developer REST API service, the Management REST API service (used for remote cluster management) and the Pulse monitoring tool’s web-based user interface.

jmx

Java management extension communications, including communications with the gfsh utility. The Pulse monitoring tool uses JMX for server-side communication with a locator, but SSL applies to this connection only if Pulse is located on an app server separate from the locator. When Pulse and the locator are colocated, JMX communication between the two does not involve a TCP connection, so SSL does not apply.

locator

Communication with and between locators

server

Communication between clients and servers

all

All of the above (use SSL system-wide)

Specifying that a component is enabled for SSL applies to the component’s server-socket side and its client-socket side. For example, if you enable SSL for locators, then any process that communicates with a locator must also have SSL enabled. If you provide “” as the value, SSL is turned off for all components.

SSL Configuration Properties

You can use Geode configuration properties to enable or disable SSL, to identify SSL ciphers and protocols, and to provide the location and credentials for key and trust stores.

ssl-enabled-components

List of components for which to enable SSL. Component list can be “” (disable SSL), “all”, or a comma-separated list of components.

ssl-endpoint-identification-enabled

A boolean value that, when set to true, causes clients to validate the server’s hostname using the server’s certificate. The default value is false. Enabling endpoint identification guards against DNS man-in-the-middle attacks when trusting certificates that are not self-signed.

ssl-use-default-context

A boolean value that, when set to true, allows Geode to use the default SSL context as returned by SSLContext.getInstance(‘Default’) or set by using SSLContext.setDefault(). When enabled, also causes ssl-endpoint-identification-enabled to be set to true.

ssl-require-authentication

Requires two-way authentication, applies to all components except web. Boolean - if true (the default), two-way authentication is required.

ssl-web-require-authentication

Requires two-way authentication for web component. Boolean - if true, two-way authentication is required. Default is false (one-way authentication only).

ssl-default-alias

A server uses one key store to hold its SSL certificates. All components on that server can share a single certificate, designated by the ssl-default-alias property. If ssl-default-alias is not specified, the first certificate in the key store acts as the default certificate.

ssl-component-alias=string

You can configure a separate certificate for any component. All certificates reside in the same key store, but can be designated by separate aliases that incorporate the component name, using this syntax, where component is the name of a component. When a component-specific alias is specified, it overrides the ssl-default-alias for the component specified.

For example, ssl-locator-alias would specify a name for the locator component’s certificate in the system key store.

ssl-ciphers

A comma-separated list of the valid ciphers for TCP/IP connections with TLS encryption enabled. A setting of 'any’ allows the JSSE provider to select an appropriate cipher that it supports.

ssl-protocols

A comma-separated list of the valid protocol versions for TCP/IP connections with TLS encryption enabled. A setting of 'any’ attempts to use your JSSE provider’s TLSv1.3, or TLSv1.2 if v1.3 is not available.

ssl-keystore, ssl-keystore-password

The path to the key store and the key store password, specified as strings

ssl-truststore, ssl-truststore-password

The path to the trust store and the trust store password, specified as strings

ssl-keystore-type, ssl-truststore-type

The types of the key store and trust store, specified as strings. The default for both is “JKS”, indicating a Java key store or trust store.

Example: secure communications throughout

To implement secure SSL communications throughout an entire cluster, each process should enable SSL for all components.

ssl-enabled-components=all
ssl-endpoint-identification-enabled=true
ssl-keystore=secure/keystore.dat
ssl-keystore-password=changeit
ssl-truststore=secure/truststore.dat
ssl-truststore-password=changeit

If the key store has multiple certificates you may want to specify the alias of the one you wish to use for each process. For instance, ssl-default-alias=Hiroki.

Example: non-secure cluster communications, secure client/server

In this example, SSL is used to secure communications between the client and the server:

Server properties

Cluster SSL is not enabled.

ssl-enabled-components=server,locator
ssl-server-alias=server
ssl-keystore=secure/keystore.dat
ssl-keystore-password=changeit
ssl-truststore=secure/truststore.dat
ssl-truststore-password=changeit
ssl-default-alias=Server-Cert

Locator properties

Cluster SSL is not enabled.

ssl-enabled-components=locator
ssl-locator-alias=locator
ssl-keystore=secure/keystore.dat
ssl-keystore-password=changeit
ssl-truststore=secure/truststore.dat
ssl-truststore-password=changeit
ssl-default-alias=Locator-Cert

Client properties

On Java clients, the list of enabled components reflects the server’s configuration so the client knows how it is expected to communicate with (for example) servers and locators. Paths to keystore and truststore are local to the client.

In this example, the client’s trust store must trust both locator and server certificates. Since the client does not specify a certificate alias, SSL will use the default certificate in its key store.

ssl-enabled-components=server,locator
ssl-endpoint-identification-enabled=true
ssl-keystore=secret/keystore.dat
ssl-keystore-password=changeit
ssl-truststore=secret/truststore.dat
ssl-truststore-password=changeit

SSL Property Reference Tables

The following table lists the components you can configure to use SSL.

Table 1. SSL-Configurable Components

Component	Communication Types
cluster	Peer-to-peer communications among members of a cluster
gateway	Communication across WAN gateways from one site to another
web	Web-based communication, including REST interfaces
jmx	Java management extension communications, including gfsh
locator	Communication with and between locators
server	Communication between clients and servers
all	All of the above

The following table lists the properties you can use to configure SSL on your Geode system.

Table 2. SSL Configuration Properties

Property	Description	Value
ssl‑enabled‑components	list of components for which to enable SSL	“all”, “”, or comma-separated list of components: cluster, gateway, web, jmx, locator, server
ssl‑endpoint‑identification‑enabled	causes clients to validate server hostname using server certificate	boolean - if true, does validation; defaults to false
ssl‑use‑default‑context	allows Geode to use the default SSL context	boolean - if true, uses the default SSL context. Also sets ssl-endpoint-identification-enabled to true; defaults to false
ssl-require-authentication	requires two-way authentication, applies to all components except web	boolean - if true (the default), two-way authentication is required
ssl‑web‑require‑authentication	requires two-way authentication for web component	boolean - if true, two-way authentication is required. Default is false (one-way authentication only)
ssl-default-alias	default certificate name	string - if empty, use first certificate in key store
ssl-component-alias	component-specific certificate name	string - applies to specified component
ssl-ciphers	list of SSL ciphers	comma-separated list (default “any”)
ssl-protocols	list of SSL protocols	comma-separated list (default “any”)
ssl-keystore	path to key store	string
ssl-keystore-password	key store password	string
ssl-truststore	path to trust store	string
ssl-truststore-password	trust store password	string

Procedure

Make sure your Java installation includes the JSSE API and familiarize yourself with its use. For information, see the Oracle JSSE website.
Configure SSL as needed for each connection type:
1. Use locators for member discovery within the clusters and for client discovery of servers. See Configuring Peer-to-Peer Discovery and Configuring a Client/Server System.
2. Configure SSL properties as necessary for different component types, using the properties described above. For example, to enable SSL for communication between clients and servers you would configure properties in the gemfire.properties file similar to:
```
ssl-enabled-components=server
ssl-protocols=any
ssl-ciphers=SSL_RSA_WITH_NULL_MD5, SSL_RSA_WITH_NULL_SHA
ssl-keystore=/path/to/trusted.keystore
ssl-keystore-password=password
ssl-truststore=/path/to/trusted.keystore
ssl-truststore-password=password
```