6 Using SSL/TLS to Secure Communication
Oracle Coherence supports using the Transport Layer Security (TLS) protocol to secure communication between entities (typically clients and servers) over a network. TLS supersedes the now deprecated Secure Sockets Layer (SSL) protocol.
In Coherence, TLS is configured using Socket Providers, which you can modify to meet your specific security scenarios. Examples for these configuration options are provided throughout this chapter.
Note:
Although the terms TLS, SSL, and SSL/TLS are used interchangeably throughout Coherence documentation, it is expected and encouraged that you use a currently supported version of TLS, not SSL, to secure communication in Coherence.
This chapter includes the following sections:
- Overview of SSL/TLS
SSL/TLS is a security protocol that secures communication between entities (typically, clients and servers) over a network. SSL/TLS works by authenticating clients and servers using digital certificates and by encrypting and decrypting communication using unique keys that are associated with authenticated clients and servers. - Coherence Socket Providers
Coherence communication is configured using Socket Providers. The<socket-providers>section of the operational configuration file contains zero or more named<socket-provider>elements. - Resolving the Socket Provider URL
Some elements in a socket provider configuration are URLs. For example, the<url>element within the<key-store>element. - Using a Socket Provider in Configuration
You can configure various places in Coherence configuration files using<socket-provider>. You can configure<socket-provider>in one of two ways: either a named reference to a named socket provider in the operational configuration file, or as an in-line socket-provider configuration. - Using SSL to Secure Cluster Communication
In a Coherence cluster, all the cluster members communicate with each other over TCP in a peer-to-peer network. Each JVM is both a server that receives connections from other cluster members and a client that connects to other cluster members. - Using SSL to Secure Extend and gRPC Client Communication
Oracle Coherence supports SSL to secure communication between Coherence Extend and gRPC clients and a cluster side Extend or gRPC proxy. - Configure a Default Socket Provider for a Cache Configuration File
You can configure a socket provider in the<defaults>section of the cache configuration file. This socket provider will then apply to all the schemes in that configuration file that do not specifically configure their own socket provider, such as any remote cache services, remote invocation services, proxy services, gRPC services, and so on. - Configuring a .NET Client-Side Stream Provider
- Securing the C++ Client with SSL/TLS
The Coherence C++ Extend Client does not officially support SSL/TLS. However, you can use one of the following options to work around this limitation to run C++ extend clients securely against an SSL/TLS enabled Coherence proxy server. - Using SSL to Secure Federation Communication
Oracle Coherence supports using SSL to secure communication between cluster participants in a federated cluster. Communication is secured between federated service members and requires SSL to be configured on each cluster participant. - Coherence PeerX509 Algorithm
Oracle Coherence includes a proprietary peer trust algorithm, PeerX509, which works by assuming trust (and only trust) of the certificates that are in the trust manager keystore. It also leverages the peer-to-peer protocol features of TCMP. Specifically, for the SSL negotiation to succeed, the certificate received must be the same as one of the certificates held by the trust manager . - Specifying a Global Socket Provider
You can configure a global socket provider in the Coherence operational configuration file. When set, every server or client socket that Coherence creates will use this configuration unless it has been overridden with a specific socket provider of its own. - Specifying Passwords in Socket Provider Configuration
Java keystores and private keys can be secured with credentials, typically a password. The socket provider configuration provides several ways to specify a password. It is up to the application developer to choose the most suitable approach based on the required level of security versus simplicity of configuration. - Controlling Cipher Suite and Protocol Version Usage
An SSL socket provider can be configured to control the use of potentially weak ciphers or specific protocol versions. - Using Host Name Verification
Learn how to configure host name verification in Oracle Coherence. A host name verifier ensures that the host name in the URL to which the client connects matches the host name in the digital certificate that the server sends back as part of the SSL connection. - Configuring Client Authentication
You can use the<client-auth>element to specify whether a SSL/TLS socket provider should use one-way or two-way SSL/TLS authentication. - Using Private Key and Certificate Files
Coherence also supports using private key and certificate files directly, instead of loading them into a keystore.
Overview of SSL/TLS
SSL/TLS is a security protocol that secures communication between entities (typically, clients and servers) over a network. SSL/TLS works by authenticating clients and servers using digital certificates and by encrypting and decrypting communication using unique keys that are associated with authenticated clients and servers.
This section covers a brief description of SSL/TLS and some of the terms that will be used in the rest of this chapter.
Establishing Identity
The identity of an entity is established by using a digital certificate and public and private encryption keys. The digital certificate contains general information about the entity and contains the public encryption key embedded within it.
In Coherence, identity is controlled by an identity manager, which corresponds to an identity manager in a Java SSL context.
Establishing Trust
A digital certificate is verified by a Certificate Authority (CA) and signed using the CA's digital certificate. The CA's digital certificate establishes trust that the entity is authentic. When a connection is made, the received certificate is verified against the CA certificate's configured trust store or the JVM's default trust store.
In Coherence, trust is controlled by a trust manager configuration, which corresponds to a trust manager in a Java SSL context.
Encrypting and Decrypting Data
The digital certificate for an entity contains a public encryption key that is paired with a private encryption key. Certificates are passed between entities during an initial connection. Data is then encrypted using the public key. Data that is encrypted using the entity public key can only be decrypted using the entity private key. This ensures that only the entity that owns the public encryption key can decrypt the data.
One-Way Authentication and Two-Way Authentication
SSL communication between clients and servers is set up using either one-way or two-way authentication.
In one-way authentication, a server is required to identify itself to a client by sending its digital certificate for authentication. The client is not required to send the server a digital certificate and remains anonymous to the server.
In two-way authentication, both the client and the server must send their respective digital certificates to each other for mutual authentication. Two-way authentication provides stronger security by assuring that the identity on each side of the communication is known. Two-way TLS is also called mutual TLS (mTLS).
Oracle Coherence supports both one-way and two-way SSL. Configuration depends on various factors, such as whether this is for cluster membership, Extend or gRPC proxies, or Extend or gRPC clients.
Certificates With Extended Usage
You can add a extended usage field to restrict the uses of a certificate. The extended usage is typically one or more values. When securing Coherence communication, the extended usage must include the correct usage, typically either serverAuth or clientAuth.
The values of extended usage will differ depending on the type of Coherence communication and the specific SSL scenario. If an application only has access to certificates that are single use (that is, only serverAuth or only clientAuth), then this restricts which available SSL configurations can be used and whether mTLS or one-way TLS can be used.
The following list shows the extended usage required for certificates used to secure different parts of Coherence.
-
Cluster Membership using mTLS requires both
serverAuthandclientAuth -
Cluster Membership using one-way SSL requires
serverAuth -
Extend or gRPC proxies require
serverAuth -
Extend or gRPC clients require
clientAuth -
Federation using mTLS requires both
serverAuthandclientAuth -
Federation using one-way SSL requires
serverAuth -
Management over REST HTTP endpoint requires
serverAuth -
Metrics HTTP endpoint requires
serverAuth -
Coherence REST HTTP proxies require
serverAuth
Coherence has a custom trust protocol called PeerX509 which is similar to mTLS but does not validate extended usage. Socket providers configured with this algorithm will work with any extended usage certificate. See Coherence PeerX509 Algorithm.
Parent topic: Using SSL/TLS to Secure Communication
Coherence Socket Providers
Coherence communication is configured using Socket Providers. The <socket-providers> section of the operational configuration file contains zero or more named <socket-provider> elements.
To name the <socket-providers> element, set its id attribute. For example, if you specify <socket-providers id="ssl-config">, the socket provider configuration is named ssl-config and it can then be referenced from other parts of the Coherence operational or cache configuration files.
There are different types of socket providers in Coherence, and to use SSL, an <ssl> socket provider needs to be configured. Depending on the required security scenario, there are several XML elements that can be added to the <ssl> element. The most common are <identity-manager> and <trust-manager>.
Example 6-1 shows a basic mTLS <ssl> socket provider that is configured with an <identity-manager> keystore named server.jks that holds the private key and certificate to establish this JVMs identity, and a <trust-manager> keystore named trust.jks that holds the CA certificate to validate the certificates of client connections.
Example 6-1 Basic mTLS socket provider configuration
<socket-provider id="ssl-config">
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>Although Example 6-1 uses Java keystores, it is also possible to configure a socket provider to directly use private key and certificate files as well as plug in custom providers that can obtain keystores, keys or certificates from any location. See Using Private Key and Certificate Files.
Additionally, Example 6-1 does not configure any passwords for keystores or keys. Configuring passwords is covered in Specifying Passwords in Socket Provider Configuration.
- Configuring the Identity Manager
Use the<identity-manager>section of a socket provider to configure the identity of the socket. An identity manager requires a private key and a corresponding certificate. These can be provided either in a Java keystore, or individually as separate key and certificate files. - Configuring a Trust Manager
When configuring a socket provider, a trust manager requires one or more CA certificates to verify trust. These can be provided either in a Java keystore, or individually as separate certificate files.
Parent topic: Using SSL/TLS to Secure Communication
Configuring the Identity Manager
Use the <identity-manager> section of a socket provider to configure the identity of the socket. An identity manager requires a private key and a corresponding certificate. These can be provided either in a Java keystore, or individually as separate key and certificate files.
Note:
Some of the following examples include hard-coded password values. In production environments, avoid using hard-coded passwords which are insecure. Coherence provides several alternative ways to provide passwords. See Specifying Passwords in Socket Provider Configuration.
Using a Java keystore
To use a Java keystore containing the key and certificate pair, configure the <key-store> element inside the <identity-manager> element.
In Example 6-2, the <identity-manager> loads the key and certificate from a keystore file named server.jks.
Example 6-2 <identity-manager> configuration
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>Password Protected keystores
If the keystore is password protected, then specify the password using one of the password configuration options in the <key-store> element.
In Example 6-3, the configuration uses the <password> element in the <key-store> to set the password as foo.
Example 6-3 <identity-manager> configuration whose keystore is password protected
<identity-manager>
<key-store>
<url>file:server.jks</url>
<password>foo</password>
</key-store>
</identity-manager>Using Private Key and Certificate Files
To use key and certificate files directly, configure the <key> and <cert> elements inside the <identity-manager> element.
In Example 6-4, the <identity-manager> loads the private key from a file named server.key and the certificate from a file named server.cert.
Example 6-4 <identity-manager> configuration that loads private key and certificate files
<identity-manager>
<key>server.key</key>
<cert>server.cert</cert>
</identity-manager>Password Protected Private Keys
If the private key is encrypted and protected with a password, the credentials need to be configured in the <identity-manager> configuration using one of the supported password options.
In Example 6-5, the identity manager is configured to read the private key from a Java keystore named server.jks. The private key is protected with a password foo, which is supplied using the <password> element inside the <identity-manager> element.
Example 6-5 <identity-manager> configuration using password protected private keys
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
<password>foo</password>
</identity-manager>Note:
When using Java keystores where both the keystore and private key require a password, it is important to make sure that the two passwords are not confused in the configuration. The keystore password is inside the <key-store> element. The private key password is at the higher level inside the <identity-manager> element.
In Example 6-6, the identity manager is configured to read the private key from a file named server.key. The private key is protected with a password foo. The password is supplied using the <password> element inside the <identity-manager> element.
Example 6-6 <identity-manager> configuration using a private key
<identity-manager>
<key>server.key</key>
<cert>server.cert</cert>
<password>foo</password>
</identity-manager>Parent topic: Coherence Socket Providers
Configuring a Trust Manager
When configuring a socket provider, a trust manager requires one or more CA certificates to verify trust. These can be provided either in a Java keystore, or individually as separate certificate files.
Note:
Some of the following examples use hard coded password values. In production environments, avoid using hard coded passwords, which are insecure. Coherence has several alternative ways to provide passwords. See Specifying Passwords in Socket Provider Configuration.
Using a Java keystore
To use a Java keystore containing the CA certificates, configure the <key-store> element inside the <trust-manager> element.
In Example 6-7, the <trust-manager> element loads the CA certificates from a keystore file named trust.jks.
Example 6-7 <trust-manager> configuration
<identity-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</identity-manager>Password Protected keystores
If the keystore is password protected, then specify the password using one of the password configuration options in the <key-store> element.
In Example 6-8, the configuration uses the <password> element in the <key-store> to set the password as foo.
Example 6-8 <trust-manager> configuration whose keystore is password protected
<trust-manager>
<key-store>
<url>file:server.jks</url>
<password>foo</password>
</key-store>
</trust-manager>Using Certificate Files
To use the certificate files directly, configure the <cert> elements inside the <trust-manager> element. The <trust-manager> element can contain multiple <cert> elements.
In Example 6-9, the <trust-manager> loads the certificates from the files named ca-one.cert and ca-two.cert.
Example 6-9 <trust-manager> configuration using certificate files
<trust-manager>
<cert>ca-one.cert</cert>
<cert>ca-two.cert</cert>
</trust-manager>Parent topic: Coherence Socket Providers
Resolving the Socket Provider URL
Some elements in a socket provider configuration are URLs. For example, the <url> element within the <key-store> element.
The following is an explanation of how the values of these elements are processed to locate the resources they refer to:
- The value of the XML element is converted to a Java URI.
- If the value is a valid URI and has a URI scheme, for example
file:orhttp:, then it is assumed to be a valid URI and Coherence will try to open a stream to this URI to read the data. - If the value has no scheme, then Coherence treats it as a file on the file system or on the class path. Coherence will first assume that the value is a file name (either fully qualified or relative to the working directory) and try to locate that file. If this fails, Coherence will try to find the same file as a resource on the class path.
Parent topic: Using SSL/TLS to Secure Communication
Using a Socket Provider in Configuration
You can configure various places in Coherence configuration files using <socket-provider>. You can configure <socket-provider> in one of two ways: either a named reference to a named socket provider in the operational configuration file, or as an in-line socket-provider configuration.
Example 6-10 demonstrates an Extend proxy service in a cache configuration file. The proxy scheme is configured with a <socket-provider> element with a value of mtls which references the socket provider named mtls in the operational configuration file.
Example 6-10 Extend proxy service that references mtls socket provider
<proxy-scheme>
<scheme-name>proxy</scheme-name>
<service-name>Proxy</service-name>
<acceptor-config>
<tcp-acceptor>
<socket-provider>mtls</socket-provider>
</tcp-acceptor>
</acceptor-config>
</proxy-scheme>Example 6-11 demonstrates an Extend proxy service in a cache configuration file. The proxy scheme is configured with a <socket-provider> element containing the full socket provider configuration.
Example 6-11 Extend proxy service with inline socket provider configuration
<proxy-scheme>
<scheme-name>proxy</scheme-name>
<service-name>Proxy</service-name>
<acceptor-config>
<tcp-acceptor>
<socket-provider>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</socket-provider>
</tcp-acceptor>
</acceptor-config>
</proxy-scheme>- Configure a Socket Provider at Runtime
When using named socket providers configured in the operational configuration file, you can change the socket provider used in a configuration at runtime based on Java system properties.
Parent topic: Using SSL/TLS to Secure Communication
Configure a Socket Provider at Runtime
When using named socket providers configured in the operational configuration file, you can change the socket provider used in a configuration at runtime based on Java system properties.
The optional system-property attribute of the <socket-provider> element specifies the name of the system property used to obtain the socket provider name at runtime. This allows flexibility to choose at runtime what sort of sockets are used. For example, developers can use plain TCP in development testing, without worrying about creating keys and certificates. Then, later in system testing and production, they can specify an SSL socket provider name.
Example 6-12 shows an Extend proxy service in a cache configuration file. The proxy scheme is configured with a <socket-provider> element without a value but with a system-property attribute set to proxy.socket.provider. By default, as the <socket-provider> element has no value, no provider will be set and the proxy will use plain TCP sockets.
Example 6-12 Configuration for an Extend proxy service configured to use plain TCP sockets
<proxy-scheme>
<scheme-name>proxy</scheme-name>
<service-name>Proxy</service-name>
<acceptor-config>
<tcp-acceptor>
<socket-provider system-property="proxy.socket.provider"/>
</tcp-acceptor>
</acceptor-config>
</proxy-scheme>If the JVM is started with the system property set, then that property value will be used as the socket provider name. For example, starting Coherence with -Dproxy.socket.provider=mtls will use mtls as the socket provider name (assuming there is a socket provider named mtls configured in the operational configuration file).
Example 6-13 shows an Extend proxy service in a cache configuration file. The proxy scheme is configured with a <socket-provider> element with a value of mtls and with a system-property attribute set to proxy.socket.provider. By default, the socket provider named mtls from the operational configuration will be used. If the proxy.socket.provider system property is set, then the property value will be used as the socket provider name.
Example 6-13 Configuration for an Extend proxy service configured to use a referenced socket provider
<proxy-scheme>
<scheme-name>proxy</scheme-name>
<service-name>Proxy</service-name>
<acceptor-config>
<tcp-acceptor>
<socket-provider system-property="proxy.socket.provider">
mtls
</socket-provider>
</tcp-acceptor>
</acceptor-config>
</proxy-scheme>Parent topic: Using a Socket Provider in Configuration
Using SSL to Secure Cluster Communication
In a Coherence cluster, all the cluster members communicate with each other over TCP in a peer-to-peer network. Each JVM is both a server that receives connections from other cluster members and a client that connects to other cluster members.
In addition, it is important to realize that TCMP is a peer-to-peer protocol that generally runs in trusted environments where many cluster nodes are expected to remain connected with each other. SSL negotiation is performed once, when the connection is made, and then the connection remains connected for the lifetime of the two cluster member JVMs involved. When configuring SSL, carefully consider the implications on key and certificate administration and on performance.
The socket provider used to control cluster traffic is configured by setting the <socket-provider> element inside the <unicast-listener> element of the cluster configuration in the operational configuration file.
In Example 6-14, the XML operational configuration file sets the unicast socket provider name to ssl-config which is a reference to the socket provider named ssl-config in the <socket-providers> section.
The actual socket provider configuration will depend on the security requirements of the application.
Example 6-14 Configuration where clusters use a socket provider to configure SSL/TLS
<?xml version='1.0'?>
<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
coherence-operational-config.xsd">
<cluster-config>
<unicast-listener>
<socket-provider>ssl-config</socket-provider>
</unicast-listener>
<socket-providers>
<socket-provider id=ssl-config">
<ssl>
<!-- Actual config omitted for brevity -->
</ssl>
</socket-provider>
</socket-providers>
</cluster-config>
</coherence>- Cluster Communication Using mTLS
The most common and recommended configuration for using SSL to secure cluster communication is mTLS (or two-way TLS). To configure an<ssl>socket provider for mTLS, both identity and trust must be configured. - Cluster Communication with One-Way SSL
You can configure one-way SSL for cluster members so that a cluster member will verify trust of a server certificate that it receives when making a connection to another cluster member. A cluster member will not verify trust for a member that connects to it.
Parent topic: Using SSL/TLS to Secure Communication
Cluster Communication Using mTLS
The most common and recommended configuration for using SSL to secure cluster communication is mTLS (or two-way TLS). To configure an <ssl> socket provider for mTLS, both identity and trust must be configured.
In Example 6-15, the socket provider mtls-config is configured with an <identity-manager> element containing a keystore named server.jks and a <trust-manager> element containing a keystore named trust.jks. The <unicast-listener> <socket-provider> element is then set to mtls-config to reference the SSL socket provider.
Example 6-15 Configuration for clusters communicating over mTLS
<?xml version='1.0'?>
<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
coherence-operational-config.xsd">
<cluster-config>
<unicast-listener>
<socket-provider>mtls-config</socket-provider>
</unicast-listener>
<socket-providers>
<socket-provider id=mtls-config">
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>
</socket-providers>
</cluster-config>
</coherence>By default, when a <ssl> socket provider is configured with both identity and trust, Coherence will create a Java SSL context that is configured for mTLS.
Note:
When using a certificate with extended usage set in this configuration, the extended usage must include both serverAuth and clientAuth. The socket provider configuration is used to configure a single Java SSL Context used by both the cluster member's server sockets (used to receive connections from other cluster members) and its client sockets (used to connect to other cluster members).
Parent topic: Using SSL to Secure Cluster Communication
Cluster Communication with One-Way SSL
You can configure one-way SSL for cluster members so that a cluster member will verify trust of a server certificate that it receives when making a connection to another cluster member. A cluster member will not verify trust for a member that connects to it.
Only a single socket provider can be configured for the unicast listener, therefore the <ssl> socket provider must be configured with both identity and trust, the same as with mTLS. To specify one-way SSL, add a <client-auth> element and set its value ot none.
The <client-auth> element configures the corresponding setting in the Java SSL context which determines whether the client must send a certificate. It has three possible values:
-
none- the client does not send a certificate (even if configured with an identity key and certificate)If you want clusters to communicate over one-way SSL, then set
<client-auth>tonone. -
wanted- the client may send a certificate if it has one -
required- the client must send a certificate.If you want clusters to communicate over mTLS, then set
<client-auth>torequired.
Example 6-16 shows the unicast listener configuration for one-way SSL.
Example 6-16 Unicast Listener Configuration for One-way SSL
<?xml version='1.0'?>
<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
coherence-operational-config.xsd">
<cluster-config>
<unicast-listener>
<socket-provider>one-way-config</socket-provider>
</unicast-listener>
<socket-providers>
<socket-provider id=one-way-config>
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
<!-- This element changes the configuration to one-way SSL -->
<client-auth>none<client-auth>
</ssl>
</socket-provider>
</socket-providers>
</cluster-config>
</coherence>Note:
When using a certificate with extended usage set in this configuration, the extended usage must include serverAuth. In one-way SSL, only the server sends a certificate to the client, so the certificate must be valid for use as a server certificate.
Parent topic: Using SSL to Secure Cluster Communication
Using SSL to Secure Extend and gRPC Client Communication
Oracle Coherence supports SSL to secure communication between Coherence Extend and gRPC clients and a cluster side Extend or gRPC proxy.
When SSL is used to secure communication between clients and proxies, it requires configuration on both the client side and the cluster side. SSL is supported for both Java and .NET Extend clients, but not for C++ Extend clients (without additional configuration as described in Securing the C++ Client with SSL/TLS. SSL is supported for all types of gRPC client.
Both mTLS and one-way SSL can be configured for clients and proxies.
- Configuring a Cluster-Side Extend Proxy SSL Socket Provider
You can configure SSL in the cluster-side cache configuration file by defining an SSL socket provider for a proxy service. - Configuring the Cluster-Side gRPC Proxy SSL Socket Provider
The Coherence gRPC Proxy is configured using an internal proxy cache configuration file. - Configuring a Java Extend or gRPC Client SSL Socket Provider
You can configure SSL in the Extend or gRPC client cache configuration file by defining an SSL socket provider for a remote scheme.
Parent topic: Using SSL/TLS to Secure Communication
Configuring a Cluster-Side Extend Proxy SSL Socket Provider
You can configure SSL in the cluster-side cache configuration file by defining an SSL socket provider for a proxy service.
There are two options for configuring an SSL socket provider depending on the level of granularity that is required.
-
Configure the socket provider by proxy service, where each proxy service defines an SSL socket provider configuration or references a predefined configuration that is included in the operational configuration file.
-
Configure all proxy services to use the same SSL socket provider configuration by configuring a socket provider in the cache configuration
<defaults>section.
A proxy service that provides its own configuration overrides the configuration in the <defaults> section. The socket provider configuration in the <defaults> section can reference a named socket provider configuration that is included in the operational configuration file or be a full in-line socket provider configuration.
Note:
When using a certificate with extended usage set in a cluster side proxy socket provider configuration, the extended usage must include serverAuth. A proxy opens server sockets to receive client connections so the certificate must be valid for server use.
Configure an SSL Socket Provider per Extend Proxy Service
To configure an SSL socket provider for an Extend proxy service, add a <socket-provider> element within the <tcp-acceptor> element of each <proxy-scheme> definition.
Example 6-17 demonstrates a proxy scheme that configures an SSL socket provider directly in the proxy configuration in the cache configuration file.
Example 6-17 Configuration for an SSL/TLS socket provider per Extend proxy service
<proxy-scheme>
<service-name>ProxyService</service-name>
<acceptor-config>
<tcp-acceptor>
<socket-provider>
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>
</tcp-acceptor>
</acceptor-config>
<autostart>true</autostart>
</proxy-scheme>Example 6-18 demonstrates configuring the proxy in the cache configuration to reference a named socket provider in the operational configuration file. In this case, the proxy will use the socket provider named ssl-config.
Example 6-18 Configuration for a single SSL/TLS socket provider for all Extend proxy services
<proxy-scheme>
<service-name>ProxyService</service-name>
<acceptor-config>
<tcp-acceptor>
<socket-provider>ssl-config</socket-provider>
</tcp-acceptor>
</acceptor-config>
<autostart>true</autostart>
</proxy-scheme>Extend or gRPC Proxy with mTLS
A proxy can be configured for mTLS using a <ssl> socket provider configured with both identity and trust.
Example 6-19 shows a socket provider configured for mTLS. By default, when a socket provider has both identity and trust configured, it will configure the SSL context to use two-way SSL.
Note:
If a proxy is configured for mTLS, then the client must also be configured for mTLS.
Example 6-19 Configuration for an Extend or gRPC Proxy using mTLS
<socket-provider id="mtls-config">
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>Extend or gRPC Proxy with One-Way SSL
A proxy can be configured for one-way SSL using a <ssl> socket provider configured with only identity. In one-way SSL, the server sends a certificate to the client, which the client verifies against its trust store. When configuring one-way SSL it is important to set the socket provider configuration correctly, that is, the server only has <identity-manager> configured and the client has a <trust-manager> configured.
Example 6-20 shows a cluster side proxy socket provider configured for one-way SSL.
Example 6-20 Configuration for an Extend or gRPC Proxy using one-way SSL/TLS
<socket-provider id="oneway-proxy-config">
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
</ssl>
</socket-provider>An alternative way to configure a cluster side proxy to use one-way SSL in a socket provider configured with both <identity-manager> and <trust-manager> is to set the <client-auth> element to none.
Example 6-21 shows a cluster side socket provider configured with both identity and trust which would normally be mTLS, but with the <client-auth> element set to none will be one-way and not require the client to send a certificate.
If a proxy is configured for one-way SSL, then the client may be configured with either an mTLS or a one-way configuration. If the client is configured as two-way (that is, it has identity and trust) it will still connect and verify the server certificate, but it will not send its own certificate.
Example 6-21 Configuration for an Extend or gRPC Proxy using one-way SSL/TLS by setting <client-auth> to none
<socket-provider id="one-way-config">
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
<!-- This element changes the configuration to one-way SSL -->
<client-auth>none<client-auth>
</ssl>
</socket-provider>Parent topic: Using SSL to Secure Extend and gRPC Client Communication
Configuring the Cluster-Side gRPC Proxy SSL Socket Provider
The Coherence gRPC Proxy is configured using an internal proxy cache configuration file.
To configure SSL for the gRPC proxy, configure a named socket provider in the operational configuration file, then set the coherence.grpc.server.socketprovider system property (or environment variable) to the name of that socket provider.
The Coherence operational configuration contains a special gRPC socket provider configuration named grpc-insecure. This configures the default gRPC Java insecure credentials for use by the proxy or client.
Parent topic: Using SSL to Secure Extend and gRPC Client Communication
Configuring a Java Extend or gRPC Client SSL Socket Provider
You can configure SSL in the Extend or gRPC client cache configuration file by defining an SSL socket provider for a remote scheme.
There are two options for configuring an SSL socket provider, depending on the level of granularity that is required.
-
Configure the socket provider per remote scheme, where each remote scheme defines an SSL socket provider configuration or references a predefined configuration that is included in the operational configuration file.
-
Configure all remote schemes to use the same SSL socket provider configuration by configuring a socket provider in the cache configuration
<defaults>section.
A remote service that provides its own configuration overrides the configuration in the <defaults> section. The socket provider configuration in the <defaults> section can reference a named socket provider configuration that is included in the operational configuration file or be a full in-line socket provider configuration.
Note:
-
When using certificate with extended usage set in an Extend or gRPC client socket provider configuration, the extended usage must include
clientAuth. -
If the cluster side proxy is configured to use mTLS, then the client must also be configured for mTLS. If the cluster side proxy is configured to use one-way SSL, then the client may be configured as either one-way or mTLS. This is because it is the server that determines whether a connection is two-way or one-way (that is, whether the client should send its identity certificate).
Configure an SSL Socket Provider per Remote Service
To configure an SSL socket provider for an Extend remote service, add a <socket-provider> element within the <tcp-initiator> element of a <remote-cache-scheme> definition or a <remove-invocation-scheme>.
To configure an SSL socket provider for a gRPC remote service, add a <socket-provider> element within the <grpc-channel> element of a <remote-grpc-cache-scheme> definition.
Example 6-22 demonstrates an Extend remote cache scheme that configures a socket provider that uses SSL. This example configures both an identity keystore (server.jks) and a trust keystore (trust.jks). This is typical of two-way SSL authentication, in which both the client and proxy must exchange digital certificates and confirm each other's identity.
Example 6-22 Configuration for an SSL/TLS socket provider per remote scheme
<?xml version="1.0"?>
<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
coherence-cache-config.xsd">
<caching-scheme-mapping>
<cache-mapping>
<cache-name>*</cache-name>
<scheme-name>remote-cache</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<remote-cache-scheme>
<scheme-name>remote-cache</scheme-name>
<service-name>RemoteService</service-name>
<initiator-config>
<tcp-initiator>
<socket-provider>
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>
</tcp-initiator>
</initiator-config>
</remote-cache-scheme>
</caching-schemes>
</cache-config>Example 6-23 demonstrates a gRPC remote cache scheme that configures a socket provider that uses SSL. This example configures both an identity keystore (server.jks) and a trust keystore (trust.jks). This is typical of two-way SSL authentication, in which both the client and proxy must exchange digital certificates and confirm each other's identity.
Example 6-23 Configuration for a gRPC remote cache scheme that configures a socket provider to use SSL/TLS
<?xml version="1.0"?>
<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
coherence-cache-config.xsd">
<caching-scheme-mapping>
<cache-mapping>
<cache-name>*</cache-name>
<scheme-name>remote-cache</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<remote-grpc-cache-scheme>
<scheme-name>remote-cache</scheme-name>
<service-name>RemoteService</service-name>
<grpc-channel>
<socket-provider>
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>
</grpc-channel>
</remote-grpc-cache-scheme>
</caching-schemes>
</cache-config>Example 6-24 configures remote schemes that references an SSL socket provider configuration named ssl-client that is defined in the <socket-providers> element of the operational configuration file.
Example 6-24 Configuration for a remote cache scheme that references a socket provider
<?xml version="1.0"?>
<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
coherence-cache-config.xsd">
<caching-scheme-mapping>
<cache-mapping>
<cache-name>extend-*</cache-name>
<scheme-name>remote-cache</scheme-name>
</cache-mapping>
<cache-mapping>
<cache-name>grpc-*</cache-name>
<scheme-name>grpc-cache</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<remote-cache-scheme>
<scheme-name>remote-cache</scheme-name>
<service-name>RemoteCache</service-name>
<initiator-config>
<tcp-initiator>
<socket-provider>ssl-client</socket-provider>
</tcp-initiator>
</remote-cache-scheme>
<remote-grpc-cache-scheme>
<scheme-name>grpc-cache</scheme-name>
<service-name>RemoteGrpcCache</service-name>
<grpc-channel>
<socket-provider>ssl-client</socket-provider>
</grpc-channel>
</remote-grpc-cache-scheme>
</caching-schemes>
</cache-config>Extend or gRPC Client with mTLS
A client can be configured for mTLS using a <ssl> socket provider configured with both identity and trust.
Example 6-25 shows a socket provider configured for mTLS. If the cluster side proxy is configured to use mTLS the client certificate from the identity will be sent to the server. In both two-way and one-way SSL, the CA certificates in the trust store will be used to verify the proxy server identity.
Example 6-25 Configuration for an Extend or gRPC client with mTLS
<socket-provider id=mtls-config">
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>Extend or gRPC Client with One-Way SSL
A client can be configured for one-way SSL using a <ssl> socket provider configured with only a trust store. The proxy server must also be configured for one-way SSL.
Example 6-26 shows a socket provider configured for one-way SSL. The CA certificates in the trust store will be used to verify the identity of the server certificate.
Example 6-26 Configuration for an Extend or gRPC client with one-way SSL/TLS
<socket-provider id=one-way-config>
<ssl>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>Parent topic: Using SSL to Secure Extend and gRPC Client Communication
Configure a Default Socket Provider for a Cache Configuration File
You can configure a socket provider in the <defaults> section of the cache configuration file. This socket provider will then apply to all the schemes in that configuration file that do not specifically configure their own socket provider, such as any remote cache services, remote invocation services, proxy services, gRPC services, and so on.
In Example 6-27, the <defaults> section of the cache configuration file has a socket provider that references a provider named mtls from the operational configuration file. The cache configuration file contains three remote schemes, none of which have a socket provider configured so they will all use the mtls socket provider.
Example 6-27 Configuration for referencing sockets providers in the <defaults> section of cache configuration
<?xml version="1.0"?>
<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
coherence-cache-config.xsd">
<defaults>
<socket-provider>mtls</socket-provider>
</defaults>
<caching-scheme-mapping>
<cache-mapping>
<cache-name>*</cache-name>
<scheme-name>remote</scheme-name>
</cache-mapping>
<cache-mapping>
<cache-name>grpc-cache</cache-name>
<scheme-name>remote-grpc</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<remote-cache-scheme>
<scheme-name>remote</scheme-name>
<service-name>RemoteService</service-name>
</remote-cache-scheme>
<remote-invocation-scheme>
<scheme-name>invocation</scheme-name>
<service-name>RemoteInvocation</service-name>
</remote-invocation-scheme>
<remote-grpc-cache-scheme>
<scheme-name>remote-grpc</scheme-name>
<service-name>RemoteGrpcCache</service-name>
</remote-grpc-cache-scheme>
</caching-schemes>
</cache-config>In Example 6-28, the <defaults> section of the cache configuration file has a socket provider that references a provider named mtls from the operational configuration file. The cache configuration file contains three remote schemes: a remote cache scheme, a remote invocation scheme, and a remote gRPC cache scheme. The remote cache scheme and the remote invocation scheme do not specify a socket provider so they use the mtls socket provider. However, the remote gRPC scheme does have a socket provider configured and so it references a socket provider named one-way in the operational configuration file.
Example 6-28
<?xml version="1.0"?>
<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
coherence-cache-config.xsd"
xml-override="{coherence.cacheconfig.override}">
<defaults>
<socket-provider>mtls-config</socket-provider>
</defaults>
<caching-scheme-mapping>
<cache-mapping>
<cache-name>*</cache-name>
<scheme-name>remote</scheme-name>
</cache-mapping>
<cache-mapping>
<cache-name>grpc-cache</cache-name>
<scheme-name>remote-grpc</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<remote-cache-scheme>
<scheme-name>remote</scheme-name>
<service-name>RemoteService</service-name>
</remote-cache-scheme>
<remote-invocation-scheme>
<scheme-name>invocation</scheme-name>
<service-name>RemoteInvocation</service-name>
</remote-invocation-scheme>
<remote-grpc-cache-scheme>
<scheme-name>remote-grpc</scheme-name>
<service-name>RemoteGrpcCache</service-name>
<grpc-channel>
<socket-provider>one-way</socket-provider>
</grpc-channel>
</remote-grpc-cache-scheme>
</caching-schemes>
</cache-config>Parent topic: Using SSL/TLS to Secure Communication
Configuring a .NET Client-Side Stream Provider
Configure SSL in the .NET client-side cache configuration file by defining an SSL stream provider for remote services. The SSL stream provider is defined using the <stream-provider> element within the <tcp-initiator> element.
Note:
Certificates are managed on Window servers at the operating system level using the Certificate Manager. The sample configuration assumes that the Certificate Manager includes the extend proxy's certificate and the trusted CA's certificate that signed the proxy's certificate.
Example 6-29 demonstrates a remote cache scheme that configures an SSL stream provider. Refer to the cache configuration XML schema (INSTALL_DIR\config\cache-config.xsd) for details on the elements that are used to configure an SSL stream provider.
Note:
The <protocol> element support any allowed SslProtocols enumeration values as well as a comma separated list of protocol values. For example:
<protocol>Tls11,Tls12</protocol>Ensure the protocol is specified in both the client-side and server-side configuration.
Example 6-29 Sample .NET Client-Side SSL Configuration
<?xml version="1.0"?>
<cache-config xmlns="http://schemas.tangosol.com/cache"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://schemas.tangosol.com/cache
assembly://Coherence/Tangosol.Config/cache-config.xsd">
<caching-scheme-mapping>
<cache-mapping>
<cache-name>dist-extend</cache-name>
<scheme-name>extend-dist</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<remote-cache-scheme>
<scheme-name>extend-dist</scheme-name>
<service-name>ExtendTcpSSLCacheService</service-name>
<initiator-config>
<tcp-initiator>
<stream-provider>
<ssl>
<protocol>Tls12</protocol>
<local-certificates>
<certificate>
<url>C:\</url>
<password>password</password>
<flags>DefaultKeySet</flags>
</certificate>
</local-certificates>
</ssl>
</stream-provider>
<remote-addresses>
<socket-address>
<address>198.168.1.5</address>
<port>9099</port>
</socket-address>
</remote-addresses>
<connect-timeout>10s</connect-timeout>
</tcp-initiator>
<outgoing-message-handler>
<request-timeout>5s</request-timeout>
</outgoing-message-handler>
</initiator-config>
</remote-cache-scheme>
</caching-schemes>
</cache-config>
Parent topic: Using SSL/TLS to Secure Communication
Securing the C++ Client with SSL/TLS
The Coherence C++ Extend Client does not officially support SSL/TLS. However, you can use one of the following options to work around this limitation to run C++ extend clients securely against an SSL/TLS enabled Coherence proxy server.
Secure the C++ client using a Load Balancer
You can configure a load balancer such as F5 to perform encryption on behalf of your C++ client and communicate with the SSL/TLS proxy servers behind the load balancer. Refer to the documentation for the load balancer service for information on how to configure it to provide data protection.
Secure C++ Client using SSH Tunneling
When SSH tunneling is enabled, the C++ client connects to a port on the local host that the SSH client listens on. The SSH client then forwards the requests over its encrypted tunnel to the server. The server connects to the SSL/TLS enabled Coherence proxy server - usually on the same machine or in the same data center as the SSH server. You can easily find examples on how to configure an SSH tunnel. Coherence proxy servers are behind the SSH server.
Secure C++ Client in a Cloud
If you are in a cloud environment, such as Oracle Cloud Infrastructure Container Engine for Kubernetes (OKE), you can configure an NGINX container on the same pod as the C++ client to serve as an SSL/TLS proxy to communicate with the Coherence SSL/TLS proxy server. You can also use an Istio sidecar proxy or egress gateway to perform encryption on behalf of the C++ client. Refer to the corresponding documentation for your cloud environment for instructions on how to secure data to the upstream servers.
Parent topic: Using SSL/TLS to Secure Communication
Using SSL to Secure Federation Communication
Oracle Coherence supports using SSL to secure communication between cluster participants in a federated cluster. Communication is secured between federated service members and requires SSL to be configured on each cluster participant.
To use SSL to secure federation communication, you can configure the <socket-provider> element in the <federated-scheme>.
The socket provider for federation is similar to the one used for the clusters unicast sockets, that is, the socket provider configures both server and client sockets. This restricts the types of configuration that are supported.
Example 6-30 shows a <federated-scheme> with a <socket-provider> configured within the scheme definition.
Example 6-30 Configuration for using an inline <socket-provider> to configure SSL/TLS between cluster participants in a federated cluster
<federated-scheme>
<scheme-name>federated</scheme-name>
<service-name>federated</service-name>
<backing-map-scheme>
<local-scheme />
</backing-map-scheme>
<autostart>true</autostart>
<socket-provider>
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>
<topologies>
<topology>
<name>MyTopology</name>
</topology>
</topologies>
</federated-scheme>Example 6-31 shows a <federated-scheme> with a <socket-provider> that references a socket provider named ssl-federation (which has been configured in the <socket-providers> section of the operational configuration file).
Example 6-31 Configuration for using a referenced <socket-provider> to configure SSL/TLS between cluster participants in a federated cluster
<federated-scheme>
<scheme-name>federated</scheme-name>
<service-name>federated</service-name>
<backing-map-scheme>
<local-scheme />
</backing-map-scheme>
<autostart>true</autostart>
<socket-provider>ssl-federation</socket-provider>
<topologies>
<topology>
<name>MyTopology</name>
</topology>
</topologies>
</federated-scheme>- Federation with mTLS
The most common and recommended configuration for using SSL to secure federation is mTLS. To configure an<ssl>socket provider for mTLS, both identity and trust must be configured. - Federation with One-Way SSL
You can configure one-way SSL for federation participants so that a participant will verify trust of a server certificate that it receives when making a connection to another participants. A federation participant will not verify trust for a member that connects to it.
Parent topic: Using SSL/TLS to Secure Communication
Federation with mTLS
The most common and recommended configuration for using SSL to secure federation is mTLS. To configure an <ssl> socket provider for mTLS, both identity and trust must be configured.
In Example 6-32, the socket provider is configured with an <identity-manager> element that contains a keystore named server.jks, and a <trust-manager> element that contains a keystore named trust.jks. By default, when a <ssl> socket provider is configured with both identity and trust, Coherence will create a Java SSL context that is configured for mTLS.
Note:
When using certificate with extended usage set in this configuration, the extended usage must include both serverAuth and clientAuth. The socket provider configuration is used to configure a single Java SSL Context used by both the federated scheme server sockets (used to receive connections from other federations participants) and its client sockets (used to connect to other federations participants).
Example 6-32 Configuration for securing federated cluster communication over mTLS
<socket-provider>
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>Parent topic: Using SSL to Secure Federation Communication
Federation with One-Way SSL
You can configure one-way SSL for federation participants so that a participant will verify trust of a server certificate that it receives when making a connection to another participants. A federation participant will not verify trust for a member that connects to it.
Only a single socket provider can be configured for the federated scheme, therefore, the <ssl> socket provider must be configured with both identity and trust, the same as with the mTLS example. To specify one-way SSL, add a <client-auth>element and set its value to none.
The <client-auth> element is used to configure the corresponding setting in the Java SSL context which determines whether the client must send a certificate. When set to none the client does not send a certificate (even if configured with an identity key and certificate).
Example 6-33 shows the federated scheme socket provider configuration for one-way SSL.
Note:
When using certificate with extended usage set in this configuration, the extended usage must include serverAuth. In one-way SSL, only the server sends a certificate to the client, so the certificate must be valid for use as a server certificate.
Example 6-33 Configuration for securing federated cluster communication over one-way SSL/TLS
<socket-provider>
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
<!-- This element changes the configuration to one-way SSL -->
<client-auth>none<client-auth>
</ssl>
</socket-provider>Parent topic: Using SSL to Secure Federation Communication
Coherence PeerX509 Algorithm
Oracle Coherence includes a proprietary peer trust algorithm, PeerX509, which works by assuming trust (and only trust) of the certificates that are in the trust manager keystore. It also leverages the peer-to-peer protocol features of TCMP. Specifically, for the SSL negotiation to succeed, the certificate received must be the same as one of the certificates held by the trust manager .
You can configure PeerX509 by setting the <algorithm> element in the <trust-manager> element.
In Example 6-34, the trust manager uses the PeerX509 algorithm. Both the identity manager and the trust manager are configured to use the same keystore. This is a common approach for PeerX509 when used for to secure cluster membership, because all cluster members use the same configuration, and the certificate sent by the client or server socket is guaranteed to be in the trust store.
Note:
-
PeerX509 is a Coherence proprietary algorithm and is not compliant with standards such as Federal Information Processing Standards (FIPS). It may not be usable in highly restricted environments.
-
Trust is verified if the certificate received matches one of those in the trust store. There is no checking of additional certificate data such as extended usages or if the certificate is signed.
Example 6-34 Configuration where the trust manager uses the PeerX509 algorithm
<socket-provider>
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<algorithm>PeerX509</algorithm>
<key-store>
<url>file:server.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>Parent topic: Using SSL/TLS to Secure Communication
Specifying a Global Socket Provider
You can configure a global socket provider in the Coherence operational configuration file. When set, every server or client socket that Coherence creates will use this configuration unless it has been overridden with a specific socket provider of its own.
In the Coherence operational configuration file, within the <cluster-config> element, specify a <global-socket-provider> element.
In Example 6-35, the operational configuration file configures a socket provider named mtls-config that is configured for mTLS. The <global-socket-provider> element is then set to mtls-config so that this socket provider will be used everywhere.
Example 6-35 Configuration for specifying a global socket provider
<?xml version='1.0'?>
<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
coherence-operational-config.xsd">
<cluster-config>
<global-socket-provider>mtls-config</global-socket-provider>
<socket-providers>
<socket-provider id=mtls-config">
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>
</socket-providers>
</cluster-config>
</coherence>
The default operational configuration file allows the global socket provider to be set using the system property coherence.global.socketprovider (or the environment variable COHERENCE_GLOBAL_SOCKET_PROVIDER).
In Example 6-36, the operational configuration configures a socket provider named mtls-config for two-way SSL, but it does not set the global socket provider element.
Example 6-36 Configuration for a socket provider without a global socket provider
<?xml version='1.0'?>
<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
coherence-operational-config.xsd">
<cluster-config>
<socket-providers>
<socket-provider id=mtls-config">
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>
</socket-providers>
</cluster-config>
</coherence>If Coherence is now started with the system property -Dcoherence.global.socketprovider=mtls-config, then the mtls-config socket provider will be used as the global socket provider.
Note:
The global socket provider will be used for all server and client sockets. Therefore, the configured socket provider must be capable of being used for both server and client sockets. Typically, this means you should configure the global socket provider for mTLS, or for one-way SSL as described in Cluster Communication with One-Way SSL.
Parent topic: Using SSL/TLS to Secure Communication
Specifying Passwords in Socket Provider Configuration
Java keystores and private keys can be secured with credentials, typically a password. The socket provider configuration provides several ways to specify a password. It is up to the application developer to choose the most suitable approach based on the required level of security versus simplicity of configuration.
- Specify Plain Text Passwords
You can specify a plain text password directly in the XML configuration using the<password>element. - Passwords From Java System Properties
You can use the Coherence configuration system property replacement feature to specify a password using a system property. The<password>element has an optionalsystem-propertyattribute that specifies which Java system property to use to obtain the value for the XML element. - Reading Passwords From a URL
You can load a password from a URL, such as a file on the file system using the<password-urlelement. - Custom Password Providers
A password provider allows you to get the SSL passwords from any source, including those using encryption. Password providers implement thecom.tangosol.net.PasswordProviderinterface. The class has agetmethod that returns a password as a Javachararray.
Parent topic: Using SSL/TLS to Secure Communication
Specify Plain Text Passwords
You can specify a plain text password directly in the XML configuration using the <password> element.
Configuring a plain text password directly in the XML is the least secure way to specify passwords, but it is simple to use and is often used in cases such as integration testing that does not access production data. However, hardcoding a password is also inflexible; whenever the password changes, you need to update the configuration file.
In Example 6-37, the <password> element specifies a plain text password for a key store in an <identity-manager> element.
Example 6-37 Configuration with a plain text password
<identity-manager>
<key-store>
<url>file:server.jks</url>
</key-store>
<password>secret</password>
</identity-manager>Parent topic: Specifying Passwords in Socket Provider Configuration
Passwords From Java System Properties
You can use the Coherence configuration system property replacement feature to specify a password using a system property. The <password> element has an optional system-property attribute that specifies which Java system property to use to obtain the value for the XML element.
In Example 6-38, the <password> element is configured to read an encrypted private key. Its system-property attribute is set to key.credentials, so at runtime, when the XML configuration is parsed, the value of the <password> system property will be used as the password.
Using system properties is more flexible than plain text, hardcoded passwords, but it is not particularly secure. The passwords will be injected into the XML after it is loaded and stored in the Coherence configuration classes in memory in plain text.
Example 6-38 Configuration for specifying a password using Java system properties
<identity-manager>
<key>server.key</key>
<cert>server.cert</cert>
<password system-property=key.credentials/>
</identity-manager>Parent topic: Specifying Passwords in Socket Provider Configuration
Reading Passwords From a URL
You can load a password from a URL, such as a file on the file system using the <password-url element.
Example 6-39 shows an SSL socket provider configuration that reads the keystore and private key passwords from files on the file system.
-
The identity manager's keystore password is read from
/coherence/security/server-pass.txtfile. -
The private key used by the identity manager is read from
/coherence/security/key-pass.txtfile. -
The keystore password used by the trust manager is read from the
/coherence/security/trust-pass.txtfile.
Although Example 6-39 uses files, you can use any valid URL that is readable, for example, a simple HTTP URL to get the password from a web server.
Example 6-39 Configuration for retrieving passwords from a URL
<socket-provider>
<ssl>
<identity-manager>
<key-store>
<url>file:server.jks</url>
<password-url>
file:/coherence/security/server-pass.txt
</password-url>
</key-store>
<password-url>
file:/coherence/security/key-pass.txt
</password-url>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
<password-url>
file:/coherence/security/trust-pass.txt
</password-url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>Parent topic: Specifying Passwords in Socket Provider Configuration
Custom Password Providers
A password provider allows you to get the SSL passwords from any source, including those using encryption. Password providers implement the com.tangosol.net.PasswordProviderinterface. The class has a get method that returns a password as a Java char array.
Example 6-40 shows a simple password provider implementation that supplies a password char array. A real password provider would obtain the password from somewhere more secure than a hardcoded char array.
Example 6-40 Custom password provider implementation using a password char array
package com.example.security;
import com.tangosol.net.PasswordProvider;
public class GetPassword implements PasswordProvider {
public GetPassword() {
}
@Override
public char[] get()
{
return new char[]{'s', 'e', 'c', 'r', 'e', 't'};
}
}You can specify custom password providers in a socket provider configuration using the <password-provider> element. Either provide the full configuration inside the <password-provider> element, or set the value of the <password-provider> element to the name of a password provider that is configured in the <password-providers> section of the operational configuration file.
Example 6-41 uses the password provider in Example 6-40 to obtain the password for a private key in an identity manager configuration.
Example 6-41 Configuration for using a custom password provider to retrieve a password
<socket-provider>
<ssl>
<identity-manager>
<key>server.key</key>
<cert>server.cert</cert>
<password-provider>
<class-name>com.example.security.GetPassword</class-name>
</password-provider>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>Named Password Provider References
If a common password provider configuration will be used multiple times, it is simpler to provide the configuration once in the <password-providers> section of the operational configuration file and then reference the named provider from the socket provider configuration.
Example 6-42 shows a password provider specified in the <password-providers> section of the operational configuration file. The password provider has a name of MyPasswordProvider.
The named password provider can now be referenced from a socket provider.
Example 6-42 Configuration for naming a password provider for reference from a socket provider
<?xml version='1.0'?>
<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
coherence-operational-config.xsd">
<cluster-config>
<password-providers>
<password-provider id="MyPasswordProvider">
<class-name>com.example.security.GetPassword</class-name>
</password-provider>
<password-providers>
</cluster-config>
</coherence>In Example 6-43, the socket provider uses MyPasswordProvider to provide the credentials for an encrypted private key file.
This can provide a flexible method of providing passwords. The socket provider configuration refers to a named password provider, rather than a hardcoded value. At runtime, different operational configuration files can be used to provide different configurations or implementations of that named provider.
Example 6-43 Configuration for a socket provider that uses a custom password provider to provide credentials
<socket-provider>
<ssl>
<identity-manager>
<key>server.key</key>
<cert>server.cert</cert>
<password-provider>
<name>MyPasswordProvider</name>
</password-provider>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>Parameterized Password Providers
A PasswordProvider implementation can be parameterized using constructor arguments or using a static factory method with arguments.
In Example 6-44, the simple PasswordProvider has a constructor with a single int parameter. The value of the parameter determines the password returned. A real password provider would obtain the password from somewhere more secure than a hardcoded char array.
The password provider can be defined in the <password-providers> section of the operational configuration file.
Example 6-44 Parameterized password provider implementation for retrieving a password
package com.oracle.coherence.examples;
import com.tangosol.net.PasswordProvider;
public class GetPassword implements PasswordProvider {
private final int param;
public GetPassword(int param) {
this.param = param;
}
@Override
public char[] get()
{
if (param == 0) {
return new char[]{'s', 'e', 'c', 'r', 'e', 't'};
}
return new char[]{'p', 'a', 's', 's', 'w', 'o', 'r', 'd'};
}
}In Example 6-45, the password provider in Example 6-44 is configured with a name of MyPasswordProvider. The <init-params> element is used to specify the constructor parameters. In this case, a single int parameter named password-id with a value of 0 (zero).
The named password provider can now be referenced from a socket provider.
Example 6-45 Configuration for specifying constructor parameters
<?xml version='1.0'?>
<coherence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/coherence/coherence-operational-config"
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-operational-config
coherence-operational-config.xsd">
<cluster-config>
<password-providers>
<password-provider id="MyPasswordProvider">
<class-name>com.example.security.GetPassword</class-name>
<init-params>
<init-param>
<param-name>password-id</param-type>
<param-value>0</param-value>
</init-param>
</init-params>
</password-provider>
<password-providers>
</cluster-config>
</coherence>In Example 6-46, the socket provider uses MyPasswordProvider to provide the credentials for an encrypted private key file. In this case, the password provider is configured with a parameter of 0 (zero), so an int value of 0 will be passed to the constructor.
Example 6-46 Configuration for using a parameterized password provider to retrieve a password
<socket-provider>
<ssl>
<identity-manager>
<key>server.key</key>
<cert>server.cert</cert>
<password-provider>
<name>MyPasswordProvider</name>
</password-provider>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>In Example 6-47, MyPasswordProvider is used again but this time the password-id parameter is overridden to be a 1, so an int value of 1 will be passed to the password provider constructor.
Example 6-47 Configuration for using a parameterized password provider to retrieve a password with an inline parameter override
<socket-provider>
<ssl>
<identity-manager>
<key>server.key</key>
<cert>server.cert</cert>
<password-provider>
<name>MyPasswordProvider</name>
<init-params>
<init-param>
<param-name>password-id</param-name>
<param-value>1</param-value>
</init-param>
</init-params>
</password-provider>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
</key-store>
</trust-manager>
</ssl>
</socket-provider>Parent topic: Specifying Passwords in Socket Provider Configuration
Controlling Cipher Suite and Protocol Version Usage
<cipher-suites> element and the <protocol-versions> elements, respectively, and enter a list of cipher suites and protocol versions using the name element. Include the usage attribute to specify whether the cipher suites and protocol versions are allowed (value of white-list) or disallowed (value of black-list). The default value for the usage attribute if no value is specified is white-list.
For example:
<socket-provider>
<ssl>
...
<cipher-suites usage="black-list">
<name>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256</name>
</cipher-suites>
<protocol-versions usage="black-list">
<name>SSLv3</name>
</protocol-versions>
...
</ssl>
</socket-provider>
Parent topic: Using SSL/TLS to Secure Communication
Using Host Name Verification
A host name verifier is useful when an SSL client (for example, Coherence acting as an SSL client) connects to a cache server on a remote host. It helps to prevent man-in-the-middle attacks.
Coherence includes a default host name verifier, and provides the ability to create and use a custom host name verifier.
This section includes the following topics:
- Using the Default Coherence Host Name Verifier
If you are using the default Coherence host name verifier, the host name verification passes if the host name in the certificate matches the host name to which the client tries to connect. - Using a Custom Host Name Verifier
When using a custom host name verifier, the class that implements the custom host name verifier must be specified in the CLASSPATH of Coherence (when acting as an SSL client) or a standalone SSL client.
Parent topic: Using SSL/TLS to Secure Communication
Using the Default Coherence Host Name Verifier
If you are using the default Coherence host name verifier, the host name verification passes if the host name in the certificate matches the host name to which the client tries to connect.
- Verification with wildcarding.
- Verification without wildcarding, if verification with wildcarding fails.
By default, the host name verifier is not enabled for backward compatibility.
However, it is enabled in the secured production mode by default. To enable or disable
the default host name verifier, see the description for the
<hostname-verifier> element in ssl.
Verification with Wildcarding
- Have at least two dot ('.') characters.
- Must start with "*."
- Have only one "*" character.
In addition, the non-wildcarded portion of the CommonName attribute must equal the domain portion of the urlhostname parameter in a case-sensitive string comparison. The domain portion of urlhostname string is the urlhostname substring that remains after the hostname substring is removed. The hostname portion of urlhostname is the substring up to and excluding the first '.' (dot) of the urlhostname parameter string.
For example:
urlhostname: mymachine.oracle.com
CommonName: *.oracle.com
.oracle.com will compare successfully with .oracle.com.
urlhostname: mymachine.uk.oracle.com
CommonName: *.oracle.com
.uk.oracle.com will not compare successfully with .oracle.com
DNSNames obtained from the server certificate's
SubjectAlternativeNames extension may be wildcarded.
Verification without Wildcarding
If wildcarded host name verification fails, the default host name verifier performs
non-wildcarded verification. It verifies the CommonName
attribute of the server certificate's SubjectDN or the
DNSNames of the server certificate's
SubjectAlternativeNames extension against the host name in the
client URL (urlhostname). The certificate
attribute must match the urlhostname (not case sensitive)
parameter. The SubjectDN CommonName attribute is verified
first, and if successful, the SubjectAlternativeNames
attributes are not verified.
If the server certificate does not have a SubjectDN, or the
SubjectDN does not have a CommonName
attribute, then the SubjectAlternativeName attributes of type
DNSNames are compared to the
urlhostname parameter. The verification passes upon the
first successful comparison to a DNSName. For a successful
verification, the urlhostname must be equal to the
certificate attribute being compared.
If urlhostname is localhost, you can set the
coherence.security.ssl.allowLocalhost system property to
true to enable 127.0.0.1, or the default IP address of
the local machine to pass.
Parent topic: Using Host Name Verification
Using a Custom Host Name Verifier
When using a custom host name verifier, the class that implements the custom host name verifier must be specified in the CLASSPATH of Coherence (when acting as an SSL client) or a standalone SSL client.
For more information about using a custom host name verifier, see the description for
the <hostname-verifier> element in ssl.
Parent topic: Using Host Name Verification
Configuring Client Authentication
You can use the <client-auth> element to specify whether a SSL/TLS socket provider should use one-way or two-way SSL/TLS authentication.
To apply <client-auth>, you must configure a socket provider with both an <identity-manager> and a <trust-manager> element in its XML configuration. If no <trust-manager> is configured, then only one-way authentication can be used. When a <trust-manager> is configured, Coherence will default to using two-way authentication.
<client-auth> is an enumeration with three valid values.
| Value | Description |
|---|---|
none |
The socket provider does not request an authentication certificate from the client. |
wanted |
The socket provider requests an authentication certificate from the client, but the client is not required to send one.
Corresponds to the |
required |
The socket provider requires that the client send an authentication certificate.
Corresponds to the |
Example 6-48 Sample One-Way SSL/TLS Authentication
The <client-auth> element is set to none so Coherence uses one-way SSL/TLS authentication, even though a trust manager has been configured.
In this case, on the SSL/TLS Engine, both want client auth and need client auth would be set to false .
...
<cluster-config>
<socket-providers>
<socket-provider id="mySSLConfig">
<ssl>
<protocol>TLS</protocol>
<identity-manager>
<key-store>
<url>file:server.jks</url>
<password>password</password>
</key-store>
<password>password</password>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
<password>password</password>
</key-store>
</trust-manager>
<client-auth>none</client-auth>
</ssl>
</socket-provider>
</socket-providers>
</cluster-config>Example 6-49 Sample Optional Client Auth
The <client-auth> element is set to wanted so the client may send a certificate but is not required to.
In this case, on the SSL/TLS Engine, want client auth would be set to true and need client auth would be set to false .
...
<cluster-config>
<socket-providers>
<socket-provider id="mySSLConfig">
<ssl>
<protocol>TLS</protocol>
<identity-manager>
<key-store>
<url>file:server.jks</url>
<password>password</password>
</key-store>
<password>password</password>
</identity-manager>
<trust-manager>
<key-store>
<url>file:trust.jks</url>
<password>password</password>
</key-store>
</trust-manager>
<client-auth>wanted</client-auth>
</ssl>
</socket-provider>
</socket-providers>
</cluster-config>Parent topic: Using SSL/TLS to Secure Communication
Using Private Key and Certificate Files
Note:
Out of the box, Coherence only supports file formats supported by the JDK. These are private key files in PEM format (that is, a file with a header of-----BEGIN RSA PRIVATE KEY----- or -----BEGIN ENCRYPTED PRIVATE KEY-----) and X509 certificate files (that is, a file with a header of -----BEGIN CERTIFICATE-----).
Parent topic: Using SSL/TLS to Secure Communication
Configuring an Identity Manager
When configuring an <identity-manager> element of a socket
provider, instead of the <keystore> element, the
<key> and <cert> elements can be used to
supply the private key a certificate file locations. The value for both the
<key> and <cert> element is a URL from which
to load the key or certificate data.
Example 6-50 shows an <identity-manager> configuration that uses a private key
loaded from the /coherence/security/client.pem file and a
certificate loaded from the /coherence/security/client.cert
file.
Example 6-50 Sample Identity Manager Using a Private Key and a Certificate File
<socket-provider>
<ssl>
<identity-manager>
<key>file:/coherence/security/client.pem</key>
<cert>file:/coherence/security/client.cert</cert>
</identity-manager>
</ssl>
</socket-provider>When configuring an <identity-manager> element, the
<keystore> element, and the <key> and
<cert> elements are mutually exclusive; either configure a
keystore, or a key and certificate. The Coherence operational configuration XSD
validation does not allow both.
Parent topic: Using Private Key and Certificate Files
Configuring a Trust Manager
When configuring a <trust-manager> element of a socket provider,
instead of the <keystore> element, one or more
<cert> elements can be used to supply the certificate file
locations. The value for the <cert> element is a URL from which to
load the certificate data.
Example 6-51 shows a <trust-manager> configuration that uses a certificate
loaded from the /coherence/security/server-ca.cert file.
Example 6-51 Sample Trust Manager Using a Certificate File
<socket-provider>
<ssl>
<trust-manager>
<cert>file:/coherence/security/server-ca.cert</cert>
</trust-manager>
</ssl>
</socket-provider>When configuring a <trust-manager> element, the
<keystore> element and the <cert>
elements are mutually exclusive; either configure a keystore, or one or more
certificates. The Coherence operational configuration XSD validation does not allow
both.
Parent topic: Using Private Key and Certificate Files