Page tree
Skip to end of metadata
Go to start of metadata

This document is in response to GEODE-420.


The current SSL configuration options in Geode have problems and are difficult to use.


For instance, if you implement SSL communications for client/server but do not do so in the server cluster the client will not be able to communicate with the locator using SSL because there is no option to have both SSL and non-SSL communications in the locator.


To simplify this we propose that


  1. there is a single set of configuration options for SSL keystore, truststore, protocols and cipher-suites

  2. a new "locator" component be added to the mix of cluster, server, web and gateway components for SSL configuration

  3. SSL can be enabled for all components or for selected components

  4. Each component can be assigned an alias for certificate lookup in the key store.  If an alias is not assigned to a component it will use the default certificate in the key store.


This simplifies things by only requiring one keystore and one truststore for a server.  Today this is only possible if all of the components in the server use the same certificate, which is likely to be the case but not a given.


The locator component can now be configured independently of the server cluster.  This allows a server cluster to run with non-SSL communications, except for initial contact with the locator, while client/server and gateway can use SSL communications.


Note for people used to GemFire: GemFire cluster members periodically contacted the locator to renew discovery information.  This is not the case with Geode where, since the implementation of a new group membership service (see GEODE-77) the locator is only used at startup.

Basic Settings:


Except for the first two settings these are all of the same character as the current cluster-ssl settings.  The only difference here is that they apply to all SSL connections.


SSL is either enabled for all components or for specific components.  Specifying that SSL is enabled for a component applies to the server-socket side and the client-socket side.  That is, if you have a locator with SSL enabled then any process that is going to communicate with that locator must have SSL enabled for the locator component.  There are some examples further down in this document showing how to do this.


ssl-enabled-components=[all, cluster, server, gateway, locator, web, jmx]

all = any component being used will have SSL enabled

cluster = p2p communications

server = communication between client and server

gateway = communication between WAN gateways

locator = communication between locators

web = web-based communication

jmx = java management extension communications

Using component names like this is extensible so we will have minimal configuration changes if we add a new component.


ssl-require-authentication=[true,false] (default "true")  – all component except web will be goverend by this setting

ssl-web-require-authentication=[true,false] (default "false") – the web service (REST) can disable/enable mutual SSL authentication, due to the nature of how users use the web.

ssl-default-alias=[empty,string] (default - use first cert in keystore)

ssl-protocols=comma separated list (default "any")

ssl-ciphers=comma separated list (default "any")





Alias overrides:


Alias overrides allow you to configure different certificates for each component.  They override ssl-default-alias for the specified component.


ssl-<component name>-alias=string  e.g ssl-server-alias, ssl-jmx-alias

Example: secure communications throughout


Each process needs to set these properties:








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,



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



ssl-enabled-components=server,locator  NOTE: cluster SSL not enabled








ssl-enabled-components=locator         NOTE: cluster SSL not enabled














The client's trust store must trust both locator and server certificates.

Since the client did not specify a certificate alias SSL will use the default certificate in its key store.



  1. Should each component have an option to enable/disable ssl-require-authentication? All components except web should generally NOT disable mutual authentication. This would promote non-authenticated servers/clients connecting to the system. This is a security hole that we need the user to be aware of if they want to disable mutual authentication.

  2. Most web services, for instance, don't require client authentication.    Resolution: new setting added.... ssl-web-require-authentication

  • No labels


  1. I would suggest for sake of aesthetics that the properties be "ssl-xxx". For consistency with the Java world I would suggest "".

    1. You have a good point.  I used caps for SSL to avoid any name-collision with the old properties but it may not be necessary.

  2. The one thing that might be a bit confusing is the locator. If I want to secure all client to server communication, or all gateway communication, then I have to include locator as well, right? Maybe it would work without it, but there will be unencrypted communication between the client and the locator. Should the locator be enabled by default if server or gateway is specified?

    1. The locator component is really what started this whole initiative going.  With the current settings it's impossible to have non-SSL P2P communications but have SSL between clients and servers because the locator uses the P2P settings to configure its socket.  Breaking the locator out into a separate component allows us to turn on SSL for it and tell servers that they need to communicate with it via SSL while the rest of P2P communication (even with the Locator at the cache-level) can use non-SSL sockets.

      Realistically we think that most folks who use SSL will have it enabled everywhere and will just set SSL-enabled-components=all.


  3. If I have two clusters connected over WAN, and only want to secure the WAN channel, how can this proposal help implement such a scenario? If I understand the proposal correctly, the locator component secures the locator-locator and client-locator channel; what this would mean is that for the above scenario, because I have to secure locator-locator over WAN, I would be required to configure client-locator (within the same distributed system) over ssl as well.

    1. Yes, that's correct.  The locator service is either secured or not secured.  Having separate location services for WAN, client/server and cluster can be discussed as a separate project.  It would require having different ports for each and I think we would want to look at cleaning up the whole notion of and the jumble of settings it currently holds at the same time.

  4. Comment submitted by klund in email: 

    I'd prefer HTTP be renamed to Web or other non-protocol word -- HTTP is
    a protocol and the names of the other channels are conceptual channels
    rather than a protocol (the others use TCP/IP or RMI but we don't label
    them as such).

    This proposal received widespread agreement; the spec was changed accordingly.