10 Using Network Filters

This chapter provides instructions for using the network filters that are included with Coherence and instructions for creating custom network filters.

Note:

Network filters are deprecated and will be desupported. Current encryption filter implementations must be migrated to use SSL. See Oracle Coherence Security Guide for detailed instructions on using SSL. There is no replacement for the compression filter.

The following sections are included in this chapter:

10.1 Overview of Network Filters

A network 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 includes the following predefined filters and also supports custom filters as required.

  • Compression Filter – compresses messages to reduce network load.

  • Symmetric Encryption Filter – protects network communication using symmetric encryption. Using SSL is strongly recommended instead of using this filter. See Oracle Coherence Security Guide.

  • PKCS Encryption Filter – protects network communication using asymmetric encryption. Using SSL is strongly recommended instead of using this filter. See Oracle Coherence Security Guide.

The predefined filters are defined in the operational deployment descriptor and must be explicitly enabled within a tangosol-coherence-override.xml file.

Note:

Use filters in an all-or-nothing manner: if one cluster member is using a filter and another is not, the messaging protocol fails. Stop the entire cluster before configuring filters.

10.2 Using the Compression Filter

The compression filter is based on the java.util.zip package and compresses message contents to reduce network load. This filter is useful when there is ample CPU available but insufficient network bandwidth. The compression filter is defined in the com.tangosol.net.CompressionFilter class and declared in the operational deployment descriptor within the <filters> node. The compression filter's configured name is gzip, which is used when enabling the filter for specific services or when enabling the filter for all services.

The following topics are included in this section:

10.2.1 Enabling the Compression Filter for Specific Services

To enable the compression filter for a specific service, include the <use-filters> element within the service's definition and add a <filter-name> subelement that is set to gzip. The following example configures the Distributed Cache service definition to enable the compression filter. All services that are instances of this service automatically use the filter.

<?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>
      <services>         <service id="3">            <service-type>DistributedCache</service-type>            <service-component>PartitionedService.PartitionedCache            </service-component>            <use-filters>               <filter-name>gzip</filter-name>            </use-filters>         </service>      </services>
   </cluster-config>
</coherence>

10.2.2 Enabling the Compression Filter for All Services

To enable the compression filter for all services, add the <use-filters> element within the <outgoing-message-handler> element and add a <filter-name> subelement that is set to gzip. For example:

<?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>
      <outgoing-message-handler>
         <use-filters>
            <filter-name>gzip</filter-name>
         </use-filters>
      </outgoing-message-handler>
   </cluster-config>
</coherence>

10.2.3 Configuring the Compression Filter

The compression filter includes parameters that can configure the filter's behavior. Table 10-1 describes each of the parameters that are available. See java.util.zip.Deflater for additional details.

The following example demonstrates configuring the compression filter and changes the default compression strategy and level:

<?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>
      <filters>
         <filter id="1">
            <filter-name>gzip</filter-name>
            <filter-class>com.tangosol.net.CompressionFilter</filter-class>
            <init-params>
               <init-param id="1">
                  <param-name>strategy</param-name>
                  <param-value>huffman-only</param-value>
               </init-param>
               <init-param id="2">
                  <param-name>level</param-name>
                  <param-value>speed</param-value>
               </init-param>
            </init-params>
         </filter>
      </filters>
   </cluster-config>
</coherence>

Table 10-1 Compression Filter Parameters

Parameter Name Description

buffer-length

Specifies compression buffer length in bytes. Legal values are positive integers or zero. The default value is 0.

level

Specifies the compression level. Legal values are:

  • default (default)

  • compression

  • speed

  • none

strategy

Specifies the compressions strategy. Legal values are:

  • gzip (default)

  • huffman-only

  • filtered

  • default


10.3 Using the Encryption Filters

Coherence ships with two JCA-based encryption filters which can protect the privacy and authenticity of cluster communications: The Symmetric Encryption Filter and the PKCS Encryption Filter.

Note:

Using SSL is strongly recommended instead of using the encryption filters. See Oracle Coherence Security Guide.

The following topics are included in this Section:

10.3.1 Enabling the 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, modify specific service definitions to include the filter or enable it for all cluster traffic. The following example enables the filter for all cluster traffic.

<?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>
      <outgoing-message-handler>
         <use-filters>
            <filter-name>symmetric-encryption</filter-name>
         </use-filters>
      </outgoing-message-handler>
   </cluster-config>
</coherence>

The shared password may either be specified in the <filter> section of the tangosol-coherence-override.xml file, or by using the tangosol.coherence.security.password system property.

10.3.1.1 Symmetric Encryption Filter Parameters

The symmetric encryption filter supports the parameters listed in Table 10-2. See the com.tangosol.net.security.PasswordBasedEncryptionFilter Javadoc for additional configuration details.

Table 10-2 Symmetric Encryption Filter Parameters

Parameter Name Description

algorithm

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

iterations

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

password

Specifies the raw material used to generate the secret key. The system property override is tangosol.coherence.security.password.

salt

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


10.3.2 Enabling the 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.

Note:

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, there is 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.

Note:

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.

Lastly, enable the filter for all cluster services by specifying it in the <outgoing-message-handler> element.

<?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>
      <outgoing-message-handler>
         <use-filters>
            <filter-name>pkcs-encryption</filter-name>
         </use-filters>
      </outgoing-message-handler>
   </cluster-config>
</coherence>

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

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

Note:

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".

10.3.2.1 PKCS Encryption Filter Parameters

Table 10-3 lists the parameters supported by the PKCS encryption filter. See the com.tangosol.net.security.ClusterEncryptionFilter Javadoc for additional configuration details.

Table 10-3 PKCS Encryption Filter Parameters

Parameter Name Description

asymmetricFilterClassName

Specifies the asymmetric filter implementation. Default value is com.tangosol.net.security.AsymmetricEncryptionFilter.

keyAlias

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

keyPassword

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

store

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

sharedKeySize

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

sharedKeyType

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

storePassword

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

storeType

Specifies the type of KeyStore. Default value is JKS.

transformation

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


10.4 Using Custom Network Filters

Custom network filters can be created as required. Custom filters must implement the com.tangosol.io.WrapperStreamFactory interface and can optionally implement the com.tangosol.run.xml.XmlConfigurable 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 configures the filter after instantiating it. See Oracle Coherence Java API Reference for details on these APIs.

The following topics are included in this section:

10.4.1 Declaring a Custom Filter

Custom filters are declared within the <filters> element in the tangosol-coherence-override.xml file. The following example demonstrates defining a custom filter named MyFilter. When declaring a custom filter, the filter id must be greater than 3 because there are three predefined filters that are declared in the operational deployment descriptor.

<?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>
      <filters>
         <filter id="4">
            <filter-name>MyFilter</filter-name>
            <filter-class>package.MyFilter</filter-class>
            <init-params>
               <init-param id="1">
                  <param-name>foo</param-name>
                  <param-value>bar</param-value>
               </init-param>
            </init-params>
         </filter>
      </filters>
   </cluster-config>
</coherence>

10.4.2 Enabling a Custom Filter for Specific Services

To enable a custom filter for a specific service, include the <use-filters> element within the service's definition and add a <filter-name> subelement that is set to the filters name. The following example enables a custom filter called MyFilter for the Distributed Cache service. All caches that are derived from this service automatically use the filter. Coherence instantiates the filter when the service starts and holds it until the service stops.

<?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>
      <services>
         <service id="3">
            <service-type>DistributedCache</service-type>
            <service-component>PartitionedService.PartitionedCache
            </service-component>
            <use-filters>
               <filter-name>MyFilter</filter-name>
            </use-filters>
         </service>
      </services>
   </cluster-config>
</coherence>

10.4.3 Enabling a Custom Filter for All Services

To enable a custom filter globally for all services, add the <use-filters> element within the <outgoing-message-handler> element and add a <filter-name> subelement that is set to the filter name. The following example enables a custom filter called MyFilter for all services. Coherence instantiates the filter on startup and holds it until the cluster stops.

<?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>
      <outgoing-message-handler>
         <use-filters>
            <filter-name>MyFilter</filter-name>
         </use-filters>
      </outgoing-message-handler>
   </cluster-config>
</coherence>