org.jgroups.protocols

Class ENCRYPT

java.lang.Object

org.jgroups.stack.Protocol

org.jgroups.protocols.ENCRYPT

Deprecated.

Use ASYM_ENCRYPT or SYM_ENCRYPT instead

@Deprecated
public class ENCRYPT
extends Protocol

ENCRYPT layer. Encrypt and decrypt communication in JGroups This class can be used in two ways:

• Option 1. Configured with a secretKey in a keystore so it can be used at any layer in JGroups without the need for a coordinator, or if you want protection against passive monitoring but do not want the key exchange overhead and complexity. In this mode all nodes must be distributed with the same keystore file.
• Option 2. Configured with algorithms and key sizes. The ENCRYPT layer in this mode sould be placed above the GMS protocol in the configuration. The coordinator then chooses the secretkey which it distributes amongst all the peers. In this form, no keystore exists as the keys are distributed using a public/private key exchange. View changes that identify a new controller will result in a new session key being generated and then distributed to all peers. This overhead can be substantial in a an application with a reasonable peer churn.

Each message is identified as encrypted with a specific encryption header which identifies the type of encrypt header and an MD5 digest that identifies the version of the key being used to encrypt/decrypt the messages.

Option 1

This is the simplest option and can be used by simply inserting the Encryption layer at any point in the JGroups stack - it will encrypt all Events of a type MSG that have a non-null message buffer. The format of the entry in this form is:
<ENCRYPT key_store_name="defaultStore.keystore" store_password="changeit" alias="myKey"/>
An example showing the keystore version can be found in the conf in a file called EncryptKeyStore.xml - along with a defaultStore.keystore file.
In order to use the ENCRYPT layer in this manner, it is necessary to have the secretKey already generated in a keystore file. The directory containing the keystore file must be on the application's classpath. You cannot create a SecretKey keystore file using the keytool application shipped with the JDK. A java file called KeyStoreGenerator is included in the demo package that can be used from the command line (or IDE) to generate a suitable keystore.

Option 2

This option is suited to an application that does not ship with a known key but instead it is generated and distributed by the controller. The secret key is first generated by the controller (in JGroups terms). When a view change occurs, a peer will request the secret key by sending a key request with its own public key. The controller encrypts the secret key with this key and sends it back to the peer who then decrypts it and installs the key as its own secret key.
All encryption and decryption of messages is done using this key. When a peer receives a view change that shows a different keyserver, it will repeat this process - the view change event also trigger the ENCRYPT layer to queue up and down messages until the new key is installed. The previous keys are retained so that messages sent before the view change that are queued can be decrypted if the key is different.
An example EncryptNoKeyStore.xml is included in the conf file as a guide.

Note: the current version does not support the concept of perfect forward encryption (PFE) which means that if a peer leaves the group the keys are re-generated preventing the departed peer from decrypting future messages if it chooses to listen in on the group. This is not included as it really requires a suitable authentication scheme as well to make this feature useful as there is nothing to stop the peer rejoining and receiving the new key. A future release will address this issue.

Author:

Steve Woodcock, Bela Ban

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	ENCRYPT.Decrypter Deprecated. Decrypts all messages in a batch, replacing encrypted messages in-place with their decrypted versions
static class	ENCRYPT.EncryptHeader Deprecated.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	asymAlgorithm Deprecated.
protected java.util.concurrent.atomic.AtomicInteger	cipher_index Deprecated.
protected int	cipher_pool_size Deprecated.
protected javax.crypto.Cipher[]	decoding_ciphers Deprecated.
protected java.util.concurrent.locks.Lock[]	decoding_locks Deprecated.
protected javax.crypto.Cipher[]	encoding_ciphers Deprecated.
protected java.util.concurrent.locks.Lock[]	encoding_locks Deprecated.
protected javax.crypto.SecretKey	secretKey Deprecated.
protected byte[]	symVersion Deprecated.

Fields inherited from class org.jgroups.stack.Protocol

after_creation_hook, down_prot, ergonomics, id, log, name, stack, stats, up_prot

Constructor Summary

Constructors

Constructor and Description
ENCRYPT() Deprecated.

Method Summary

Modifier and Type	Method and Description
java.lang.Object	down(Event evt) Deprecated. An event is to be sent down the stack.
java.lang.String	getAsymAlgorithm() Deprecated.
javax.crypto.Cipher	getAsymCipher() Deprecated.
int	getAsymInit() Deprecated.
javax.crypto.SecretKey	getDesKey() Deprecated.
Address	getKeyServerAddr() Deprecated.
java.security.KeyPair	getKpair() Deprecated.
protected int	getNextIndex() Deprecated.
javax.crypto.SecretKey	getSecretKey() Deprecated.
java.lang.String	getSymAlgorithm() Deprecated.
javax.crypto.Cipher	getSymDecodingCipher() Deprecated.
javax.crypto.Cipher	getSymEncodingCipher() Deprecated.
int	getSymInit() Deprecated.
byte[]	getSymVersion() Deprecated.
protected java.lang.Object	handleEncryptedMessage(Message msg, Event evt, ENCRYPT.EncryptHeader hdr) Deprecated.
protected void	handleUpEvent(Message msg, ENCRYPT.EncryptHeader hdr) Deprecated.
void	init() Deprecated. Called after instance has been created (null constructor) and before protocol is started.
void	initKeyPair() Deprecated. Generates the public/private key pair from the init params
void	initSymKey() Deprecated. Used to initialise the symmetric key if none is supplied in a keystore.
protected void	setKeyServerAddr(Address keyServerAddr) Deprecated.
protected void	setLocalAddress(Address local_addr) Deprecated.
java.lang.Object	up(Event evt) Deprecated. An event was received from the layer below.
void	up(MessageBatch batch) Deprecated. Sends up a multiple messages in a MessageBatch.

Methods inherited from class org.jgroups.stack.Protocol

accept, afterCreationHook, destroy, dumpStats, enableStats, getConfigurableObjects, getDownProtocol, getDownServices, getId, getIdsAbove, getLevel, getLog, getName, getProtocolStack, getSocketFactory, getThreadFactory, getTransport, getUpProtocol, getUpServices, getValue, isErgonomics, level, parse, printStats, providedDownServices, providedUpServices, requiredDownServices, requiredUpServices, resetStatistics, resetStats, setDownProtocol, setErgonomics, setId, setLevel, setProtocolStack, setSocketFactory, setUpProtocol, setValue, setValues, start, statsEnabled, stop

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

asymAlgorithm

protected java.lang.String asymAlgorithm

Deprecated.

cipher_pool_size

protected int cipher_pool_size

Deprecated.

encoding_ciphers

protected javax.crypto.Cipher[] encoding_ciphers

Deprecated.

decoding_ciphers

protected javax.crypto.Cipher[] decoding_ciphers

Deprecated.

encoding_locks

protected java.util.concurrent.locks.Lock[] encoding_locks

Deprecated.

decoding_locks

protected java.util.concurrent.locks.Lock[] decoding_locks

Deprecated.

cipher_index

protected final java.util.concurrent.atomic.AtomicInteger cipher_index

Deprecated.

symVersion

protected byte[] symVersion

Deprecated.

secretKey

protected javax.crypto.SecretKey secretKey

Deprecated.

Constructor Detail

ENCRYPT

public ENCRYPT()

Deprecated.

Method Detail

getNextIndex

protected int getNextIndex()

Deprecated.

getAsymInit

public int getAsymInit()

Deprecated.

getDesKey

public javax.crypto.SecretKey getDesKey()

Deprecated.

getKpair

public java.security.KeyPair getKpair()

Deprecated.

getAsymCipher

public javax.crypto.Cipher getAsymCipher()

Deprecated.

getSymAlgorithm

public java.lang.String getSymAlgorithm()

Deprecated.

getSymInit

public int getSymInit()

Deprecated.

getAsymAlgorithm

public java.lang.String getAsymAlgorithm()

Deprecated.

getSymVersion

public byte[] getSymVersion()

Deprecated.

getSecretKey

public javax.crypto.SecretKey getSecretKey()

Deprecated.

getSymDecodingCipher

public javax.crypto.Cipher getSymDecodingCipher()

Deprecated.

getSymEncodingCipher

public javax.crypto.Cipher getSymEncodingCipher()

Deprecated.

getKeyServerAddr

public Address getKeyServerAddr()

Deprecated.

setLocalAddress

protected void setLocalAddress(Address local_addr)

Deprecated.

setKeyServerAddr

protected void setKeyServerAddr(Address keyServerAddr)

Deprecated.

init

public void init()
          throws java.lang.Exception

Deprecated.

Description copied from class: Protocol

Called after instance has been created (null constructor) and before protocol is started. Properties are already set. Other protocols are not yet connected and events cannot yet be sent.

Overrides:

init in class Protocol

Throws:

java.lang.Exception - Thrown if protocol cannot be initialized successfully. This will cause the ProtocolStack to fail, so the channel constructor will throw an exception

initSymKey

public void initSymKey()
                throws java.lang.Exception

Deprecated.

Used to initialise the symmetric key if none is supplied in a keystore.

Throws:

java.lang.Exception

initKeyPair

public void initKeyPair()
                 throws java.lang.Exception

Deprecated.

Generates the public/private key pair from the init params

Throws:

java.lang.Exception

up

public java.lang.Object up(Event evt)

Deprecated.

Description copied from class: Protocol

An event was received from the layer below. Usually the current layer will want to examine the event type and - depending on its type - perform some computation (e.g. removing headers from a MSG event type, or updating the internal membership list when receiving a VIEW_CHANGE event). Finally the event is either a) discarded, or b) an event is sent down the stack using down_prot.down() or c) the event (or another event) is sent up the stack using up_prot.up().

Overrides:

up in class Protocol

up

public void up(MessageBatch batch)

Deprecated.

Description copied from class: Protocol

Sends up a multiple messages in a MessageBatch. The sender of the batch is always the same, and so is the destination (null == multicast messages). Messages in a batch can be OOB messages, regular messages, or mixed messages, although the transport itself will create initial MessageBatches that contain only either OOB or regular messages.

The default processing below sends messages up the stack individually, based on a matching criteria (calling Protocol.accept(org.jgroups.Message)), and - if true - calls Protocol.up(org.jgroups.Event) for that message and removes the message. If the batch is not empty, it is passed up, or else it is dropped.

Subclasses should check if there are any messages destined for them (e.g. using MessageBatch.getMatchingMessages(short,boolean)), then possibly remove and process them and finally pass the batch up to the next protocol. Protocols can also modify messages in place, e.g. ENCRYPT could decrypt all encrypted messages in the batch, not remove them, and pass the batch up when done.

Overrides:

up in class Protocol

Parameters:

batch - The message batch

handleEncryptedMessage

protected java.lang.Object handleEncryptedMessage(Message msg,
                                                  Event evt,
                                                  ENCRYPT.EncryptHeader hdr)
                                           throws java.lang.Exception

Deprecated.

Throws:

java.lang.Exception

handleUpEvent

protected void handleUpEvent(Message msg,
                             ENCRYPT.EncryptHeader hdr)

Deprecated.

down

public java.lang.Object down(Event evt)

Deprecated.

Description copied from class: Protocol

An event is to be sent down the stack. The layer may want to examine its type and perform some action on it, depending on the event's type. If the event is a message MSG, then the layer may need to add a header to it (or do nothing at all) before sending it down the stack using down_prot.down(). In case of a GET_ADDRESS event (which tries to retrieve the stack's address from one of the bottom layers), the layer may need to send a new response event back up the stack using up_prot.up().

Overrides:

down in class Protocol