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 theJCEKSstore 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.
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
-Doption 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.
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.
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:
- The secret key is generated and distributed by the coordinator.
- When a view change occurs, a peer requests the secret key by sending a key request with its own public key.
- The coordinator encrypts the secret key with the public key, and sends it back to the peer.
- The peer then decrypts and installs the key as its own secret key.
- 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.
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:
| 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
| 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
| Name | Description |
|---|---|
| change_key_on_leave | When a member leaves the view, change the secret key, preventing old members from eavesdropping. |
