10.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.
10.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.
10.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.
10.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:
- The secret key is generated and distributed by the controller.
- When a view change occurs, a peer requests the secret key by sending a key request with its own public key.
- The controller 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.
In this mode, the
ENCRYPT layer must be placed above the GMS protocol in the configuration.
Example 10.9. ENCRYPT Layer
<config <!-- Additional configuration information here --> >
<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.
10.3.4. ENCRYPT Configuration Parameters
The following table provides configuration parameters for the
ENCRYPT JGroups protocol:
| 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. |
