26.3. JGroups Encryption

JGroups includes the SYM_ENCRYPT and ASYM_ENCRYPT protocols to provide encryption for cluster traffic.

Important

The ENCRYPT protocol has been deprecated and should not be used in production environments. It is recommended to use either SYM_ENCRYPT or ASYM_ENCRYPT
By default, both of these protocols only encrypt the message body; they do 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. When defining these protocols they should be placed directly under NAKACK2.
Both protocols may be used to encrypt and decrypt communication in JGroups, and are used in the following ways:
  • SYM_ENCRYPT: Configured with a secret key in a keystore using the JCEKS store type.
  • ASYM_ENCRYPT: Configured with algorithms and key sizes. In this scenario the secret key is not retrieved from the keystore, but instead generated by the coordinator and distributed to new members. Once a member joins the cluster they send a request for the secret key to the coordinator; the coordinator responds with the secret key back to the new member encrypted with the member's public key.
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

26.3.1. Configuring JGroups Encryption Protocols

JGroups encryption protocols are placed in the JGroups configuration file, and there are three methods of including this file depending on how JBoss Data Grid is in use:
  • 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 Section 30.2, “Configure JGroups (Library Mode)” 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.
When defining both the SYM_ENCRYPT and ASYM_ENCRYPT protocols, place them directly under NAKACK2 in the configuration file.
Report a bug

26.3.2. SYM_ENCRYPT: Using a Key Store

SYM_ENCRYPT uses store type JCEKS. To generate a keystore compatible with JCEKS, use the following command line options to keytool: 
$ keytool -genseckey -alias myKey -keypass changeit -storepass changeit -keyalg Blowfish -keysize 56 -keystore defaultStore.keystore -storetype JCEKS
SYM_ENCRYPT can then be configured by adding the following information to the JGroups file used by the application. 
<SYM_ENCRYPT sym_algorithm="AES"
            encrypt_entire_message="true"
            keystore_name="defaultStore.keystore"
            store_password="changeit"
            alias="myKey"/>

Note

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

26.3.3. ASYM_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 coordinator.
  2. When a view change occurs, a peer requests the secret key by sending a key request with its own public key.
  3. The coordinator 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.
  5. Any further communications are encrypted and decrypted using the secret key.

Example 26.7. ASYM_ENCRYPT Example

    ...
    <VERIFY_SUSPECT/>
    <ASYM_ENCRYPT encrypt_entire_message="true"
             sym_keylength="128"
             sym_algorithm="AES/ECB/PKCS5Padding"
             asym_keylength="512"
             asym_algorithm="RSA"/>

    <pbcast.NAKACK2/>
    <UNICAST3/>
    <pbcast.STABLE/>
    <FRAG2/>
    <AUTH auth_class="org.jgroups.auth.MD5Token"
          auth_value="chris"
          token_hash="MD5"/>
    <pbcast.GMS join_timeout="2000" />
In the provided example, ASYM_ENCRYPT has been placed immediately below NAKACK2, and encrypt_entire_message has been enabled, indicating that the message headers will be encrypted along with the message body. This means that the NAKACK2 and UNICAST3 protocols are also encrypted. In addition, AUTH has been included as part of the configuration, so that only authenticated nodes may request the secret key from the coordinator.
View changes that identify a new controller result in a new secret key being generated and distributed to all peers. This is a substantial overhead in an application with high peer churn. A new secret key may optionally be generated when a cluster member leaves by setting change_key_on_leave to true.
When encrypting an entire message, the message must be marshalled into a byte buffer before being encrypted, resulting in decreased performance.
Report a bug

26.3.4. JGroups Encryption Configuration Parameters

The following table provides configuration parameters for the ENCRYPT JGroups protocol, which both SYM_ENCRYPT and ASYM_ENCRYPT extend:

Table 26.1. ENCRYPT Configuration Parameters

Name Description
asym_algorithm Cipher engine transformation for asymmetric algorithm. Default is RSA.
asym_keylength Initial public/private key length. Default is 512.
asym_provider Cryptographic Service Provider. Default is Bouncy Castle Provider.
encrypt_entire_message By default only the message body is encrypted. Enabling encrypt_entire_message ensures that all headers, destination and source addresses, and the message body is encrypted.
sym_algorithm Cipher engine transformation for symmetric algorithm. Default is AES.
sym_keylength Initial key length for matching symmetric algorithm. Default is 128.
sym_provider Cryptographic Service Provider. Default is Bouncy Castle Provider.
The following table provides a list of the SYM_ENCRYPT protocol parameters

Table 26.2. SYM_ENCRYPT Configuration Parameters

Name Description
alias Alias used for recovering the key. Change the default.
key_password Password for recovering the key. Change the default.
keystore_name File on classpath that contains keystore repository.
store_password Password used to check the integrity/unlock the keystore. Change the default.
The following table provides a list of the ASYM_ENCRYPT protocol parameters

Table 26.3. ASYM_ENCRYPT Configuration Parameters

Name Description
change_key_on_leave When a member leaves the view, change the secret key, preventing old members from eavesdropping.
Report a bug