9.3. JGroups ENCRYPT

JGroups includes the ENCRYPT protocol to provide encryption for cluster traffic.
By default, encryption only encrypts the message body; it does not encrypt message headers. To encrypt the entire message, including all headers, as well as destination and source addresses, the property encrypt_entire_message must be true. ENCRYPT must also be below any protocols with headers that must be encrypted.
The ENCRYPT layer is used to encrypt and decrypt communication in JGroups. The JGroups ENCRYPT protocol can be used in two ways:
  • Configured with a secretKey in a keystore.
  • Configured with algorithms and key sizes.
Each message is identified as encrypted with a specific encryption header identifying the encrypt header and an MD5 digest identifying the version of the key being used to encrypt and decrypt messages.
Report a bug

9.3.1. ENCRYPT Configured with a secretKey in a Key Store

The ENCRYPT class can be configured with a secretKey in a keystore so it is usable at any layer in JGroups without requiring a coordinator. This also provides protection against passive monitoring without the complexity of key exchange.
This method can be used by inserting the encryption layer at any point in the JGroups stack, which will encrypt all events of a type MSG that have a non-nill message buffer. The following is an example of the entry in this form: 
<ENCRYPT key_store_name="defaultStore.keystore" store_password="${VAULT::VAULT_BLOCK::ATTRIBUTE_NAME::ENCRYPTED_VALUE}"  alias="myKey"/>
The secretKey must be already generated in a keystore file in order to use the ENCRYPT layer in this manner. The directory containing the keystore file must be on the application classpath.

Note

The secretKey keystore file cannot be created using the keytool application shipped with JDK. The KeyStoreGenerator java file is included in the demo package that can be used to generate a suitable keystore.
Report a bug

9.3.2. ENCRYPT Using a Key Store

ENCRYPT uses store type JCEKS. To generate a keystore compatible with JCEKS, use the following command line options: 
$ keytool -genseckey -alias myKey -keypass changeit -storepass changeit -keyalg Blowfish -keysize 56 -keystore defaultStore.keystore -storetype JCEKS
ENCRYPT can then be configured by adding the following information to the JGroups file used by the application. 
<ENCRYPT key_store_name="defaultStore.keystore"
         store_password="${VAULT::VAULT_BLOCK::ATTRIBUTE_NAME::ENCRYPTED_VALUE}"
         alias="myKey"/>
Standard Java properties can also be used in the configuration, and it is possible to pass the path to JGroups configuration via the -D option during start up.
The default, pre-configured JGroups files are packaged in infinispan-embedded.jar, alternatively, you can create your own configuration file. See the Configure JGroups (Library Mode) section in the Red Hat JBoss Data Grid Administration and Configuration Guide for instructions on how to set up JBoss Data Grid to use custom JGroups configurations in library mode.
In Remote Client-Server mode, the JGroups configuration is part of the main server configuration file.

Note

The defaultStore.keystore must be found in the classpath.
Report a bug

9.3.3. ENCRYPT Configured with Algorithms and Key Sizes

In this encryption mode, the coordinator selects the secretKey and distributes it to all peers. There is no keystore, and keys are distributed using a public/private key exchange. Instead, encryption occurs as follows:
  1. The secret key is generated and distributed by the controller.
  2. When a view change occurs, a peer requests the secret key by sending a key request with its own public key.
  3. The controller encrypts the secret key with the public key, and sends it back to the peer.
  4. The peer then decrypts and installs the key as its own secret key.
In this mode, the ENCRYPT layer must be placed above the GMS protocol in the configuration.

Example 9.9. ENCRYPT Layer

<config ... >
    <UDP />
    <PING />
    <MERGE2 />
    <FD />
    <VERIFY_SUSPECT />
    <ENCRYPT encrypt_entire_message="false"
             sym_init="128" sym_algorithm="AES/ECB/PKCS5Padding"
             asym_init="512" asym_algorithm="RSA"/>
    <pbcast.NAKACK />
    <UNICAST />
    <pbcast.STABLE />
    <FRAG2 />
    <pbcast.GMS />
</config>
In the provided example, the sequence numbers for the NAKACK and UNICAST protocols will be encrypted.
View changes that identify a new controller result in a new session key being generated and distributed to all peers. This is a substantial overhead in an application with high peer churn.
When encrypting an entire message, the message must be marshalled into a byte buffer before being encrypted, resulting in decreased performance.
Report a bug

9.3.4. ENCRYPT Configuration Parameters

The following table provides configuration parameters for the ENCRYPT JGroups protocol:

Table 9.1. Configuration Parameters

Name Description
alias Alias used for recovering the key. Change the default.
asymAlgorithm Cipher engine transformation for asymmetric algorithm. Default is RSA.
asymInit Initial public/private key length. Default is 512.
asymProvider Cryptographic Service Provider. Default is Bouncy Castle Provider.
encrypt_entire_message  
id Give the protocol a different ID if needed so we can have multiple instances of it in the same stack.
keyPassword Password for recovering the key. Change the default.
keyStoreName File on classpath that contains keystore repository.
level Sets the logger level (see javadocs).
name Give the protocol a different name if needed so we can have multiple instances of it in the same stack.
stats Determines whether to collect statistics (and expose them via JMX). Default is true.
storePassword Password used to check the integrity/unlock the keystore. Change the default. It is recommended that passwords are stored using Vault.
symAlgorithm Cipher engine transformation for symmetric algorithm. Default is AES.
symInit Initial key length for matching symmetric algorithm. Default is 128.
Report a bug