Skip Headers
Oracle® Coherence Developer's Guide
Release 3.6.1

Part Number E15723-03
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

9 Using Network Filters

A filter is a mechanism for plugging into the low-level TCMP stream protocol. Every message that is sent across the network by Coherence is streamed through this protocol. Coherence supports custom filters. By writing a filter, the contents of the network traffic can be modified. The most common examples of modification are encryption and compression.

Compression Filters

The compression filter is based on the package and compresses message contents thus reducing the network load. This is useful when there is ample CPU available but insufficient network bandwidth. See "Configuring Filters" for information on enabling this filter.

Encryption Filters

Coherence ships with two JCA-based encryption filters which can be used to protect the clustered communications for privacy and authenticity: The Symmetric Encryption Filter and the PKCS Encryption Filter.


Using SSL is strongly recommended over encryption filters. See "Using SSL in Coherence".

Symmetric Encryption Filter

This filter uses symmetric encryption to protect cluster communications. The encryption key is generated from a shared password known to all cluster members. This filter is suitable for small deployments or where the maintenance and protection of a shared password is feasible.

To enable this filter, specify which services will have their traffic encrypted by using this filter, or to enable it for all cluster traffic you may simply specify it as a filter for the <outgoing-message-handler> element.

Example 9-1 Enabling a Filter for all Network Traffic


The shared password may either be specified in the <filters> section of the operational configuration file, or by using the system property. See "Symmetric Encryption Filter Parameters" for additional configuration options.

Symmetric Encryption Filter Parameters

The symmetric encryption filter supports the parameters listed in Table 9-1. See the Javadoc for additional configuration details.

Table 9-1 Symmetric Encryption Filter Parameters

Parameter Name Value Description


Specifies the mechanism to use in deriving a secret key from the above material. Default value is PBEWithMD5AndDES.


Specifies the iteration count to use in deriving the key. Default value is 32.


Specifies the raw material used to generate the secret key. The system property override is


Specifies the salt to use in deriving the key. Default value is nosecret.

PKCS Encryption Filter

This filter uses public key cryptography (asymmetric encryption) to protect the cluster join protocol, and then switches over to much faster symmetric encryption for service level data transfers. Unlike the symmetric encryption filter, there is no persisted shared secret. The symmetric encryption key is randomly generated by the cluster's senior member, and is securely transfer to authenticated cluster members as part of the cluster join protocol. This encryption filter is suitable for deployments where maintenance of a shared secret is not feasible.


This filter requires the JVM to be configured with a JCA public key cryptography provider implementation such as Bouncy Castle, which supports asymmetric block ciphers. See the JCA documentation for details on installing and configuring JCA providers.

In the default setup each cluster node must be configured with a Java Keystore from which it may retrieve its identity Certificate and associated private key, and a set of trusted Certificates for other cluster members. You can construct this keystore as follows:

Create a Java Keystore and the local cluster member's password protected certificate and private key.

keytool -genkey -alias local -keypass secret -keyalg rsa -storepass secret -keystore ./keystore.jks

Export this public certificate for inclusion in all cluster members keystores.

keytool -export -alias local -keypass secret -storepass secret -keystore ./keystore.jks -rfc -file local.cert

Import the Certificates of other trusted cluster members. Each certificate must be stored under a unique but otherwise unimportant alias.

keytool -import -alias remote_1 -storepass secret -keystore ./keystore.jks -file local_1.cert
keytool -import -alias remote_2 -storepass secret -keystore ./keystore.jks -file local_2.cert
keytool -import -alias remote_3 -storepass secret -keystore ./keystore.jks -file local_3.cert

At this point you will have one keystore per cluster node, each containing a single private key plus a full set of trusted public certificates. If new nodes are to be added to the cluster the keystores of all existing nodes must be updated with the new node's certificate.


You may also choose to supply custom key and trust management logic to eliminate the need for a full keystore per node. See the implementation's documentation for details on customization.

Then configure the cluster to encrypt all traffic using this filter by specifying it in the <outgoing-message-handler> element.


The keystore and alias password can be specified either in the <filters> node of the operational configuration file, or by using the system property.

Unlike the Symmetric Encryption Filter, this filter is not currently supported by Coherence*Extend, or on a service by service level.


Using this filter may require a change to the packet size configuration depending on the size of certificates used. Set the <maximum-length> to a value larger than the certificate size (allowing some overhead). See "packet-size".

PKCS Encryption Filter Parameters

The PKCS encryption filter supports the following parameters, see "Encryption Filters" section for examples, or the Javadoc for additional configuration details.

Table 9-2 PKCS Encryption Filter Parameters

Parameter Name Description


Specifies the asymmetric filter implementation. Default value is


Specifies the alias to use in reading the key from the keystore.


Specifies the password to use in reading the key. The preconfigured system property is


Specifies the path to the KeyStore Default value is .keystore.


Specifies the size of shared key. Default value is 112.


Specifies the type of shared key. Default value is DESede.


Specifies the password to use to access the store If unspecified value of keyPassword parameter will be used.


Specifies the type of KeyStore. Default value is JKS.


Specifies the transformation to use. Default value is RSA/NONE/PKCS1Padding.

Configuring Filters

There are two steps to configuring a filter.

  1. Declare the filter in the <filters> XML element of the tangosol-coherence.xml file:

    Example 9-2 Declaring a Filter in the tangosol-coherence.xml File


    See Appendix A, "Operational Configuration Elements" for more information on the structure of the <filters> XML element.

  2. The second step is to attach the filter to one or more specific services, or to make the filter global (for all services). To specify the filter for a specific service, for example the ReplicatedCache service, add a <filter-name> element to the <use-filters> element of the service declaration in the tangosol-coherence.xml file:

    Example 9-3 Attaching the Filter to a Service


To add the filter to all services, do the same under the <outgoing-message-handler> element instead of under a <service> element:

Example 9-4 Adding the Filter to All Services



Filters should be used in an all-or-nothing manner: If one cluster member is using a filter and other is not, the messaging protocol will fail. You should stop the entire cluster before configuring filters.

Creating a Custom Filter

To create a new filter, create a Java class that implements the interface and optionally implements the interface. The WrapperStreamFactory interface provides the stream to be wrapped ("filtered") on input (received message) or output (sending message) and expects a stream back that wraps the original stream. These methods are called for each incoming and outgoing message.

If the filter class implements the XmlConfigurable interface, then Coherence will configure the filter after instantiating it. Example 9-5 illustrates a filter declaration in the tangosol-coherence.xml file. If the filter is associated with a service type, every time a new service is started of that type, Coherence will instantiate the CompressionFilter class and will hold it with the service until the service stops. If the filter is associated with all outgoing messages, Coherence will instantiate the filter on startup and will hold it until the cluster stops.

Example 9-5 Configuration for a Custom Filter


After instantiating the filter, Coherence will call the setConfig method (if the filter implements XmlConfigurable) with the following XML element:

Example 9-6 Configuring a setConfig Call for a Filter