org.jgroups.protocols

## Class ENCRYPT

- java.lang.Object
- - org.jgroups.stack.Protocol
  - - org.jgroups.protocols.ENCRYPT

    public class ENCRYPT
    extends Protocol

ENCRYPT layer. Encrypt and decrypt the group communication in JGroups The file 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 used between the FRAG and PBCast layers in the stack. 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 JGroup 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 bare-bones.xml file showing the keystore version can be found in the conf ina 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 JGroup 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
`static class` `ENCRYPT.EncryptHeader`

### Field Summary

Fields
`protected java.util.concurrent.locks.Lock` `decrypt_lock` To synchronize access to symDecodingCipher

### Fields inherited from class org.jgroups.stack.Protocol

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

### Constructor Summary

Constructors
Constructor and Description
`ENCRYPT()`

### Method Summary

Methods
`java.lang.Object` `down(Event evt)` An event is to be sent down the stack.
`protected java.lang.String` `getAsymAlgorithm()`
`protected javax.crypto.Cipher` `getAsymCipher()`
`protected int` `getAsymInit()`
`protected java.lang.String` `getAsymProvider()`
`protected javax.crypto.SecretKey` `getDesKey()`
`protected Address` `getKeyServerAddr()`
`protected java.lang.String` `getKeyStoreName()`
`protected java.security.KeyPair` `getKpair()`
`protected Address` `getLocal_addr()`
`protected java.security.PublicKey` `getServerPubKey()`
`protected java.lang.String` `getSymAlgorithm()`
`protected javax.crypto.Cipher` `getSymDecodingCipher()`
`protected javax.crypto.Cipher` `getSymEncodingCipher()`
`protected int` `getSymInit()`
`protected java.lang.String` `getSymProvider()`
`void` `init()` Called after instance has been created (null constructor) and before protocol is started.
`void` `initKeyPair()` Generates the public/private key pair from the init params
`void` `initSymKey()` Used to initialise the symmetric key if none is supplied in a keystore.
`java.lang.Object` `passItDown(Event evt)`
`java.lang.Object` `passItUp(Event evt)`
`void` `reset()` Just remove if you don't need to reset any state
`protected void` `setKeyServerAddr(Address keyServerAddr)`
`protected void` `setLocal_addr(Address local_addr)`
`void` `setObserver(org.jgroups.protocols.ENCRYPT.Observer o)`
`java.lang.Object` `up(Event evt)` An event was received from the layer below.

### Methods inherited from class org.jgroups.stack.Protocol

`destroy, downThreadEnabled, dumpStats, enableStats, getConfigurableObjects, getDownProtocol, getId, getLevel, getName, getProperties, getProtocolStack, getSocketFactory, getThreadFactory, getTransport, getUpProtocol, getValue, isErgonomics, printStats, providedDownServices, providedUpServices, requiredDownServices, requiredUpServices, resetStats, setDownProtocol, setErgonomics, setId, setLevel, setProperties, setPropertiesInternal, setProperty, setProtocolStack, setSocketFactory, setUpProtocol, setValue, setValues, start, statsEnabled, stop, upThreadEnabled`

### Methods inherited from class java.lang.Object

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

### Field Detail

#### decrypt_lock

    protected final java.util.concurrent.locks.Lock decrypt_lock

To synchronize access to symDecodingCipher

### Constructor Detail

#### ENCRYPT

    public ENCRYPT()

### Method Detail

#### setObserver

    public void setObserver(org.jgroups.protocols.ENCRYPT.Observer o)

#### init

    public void init()
              throws java.lang.Exception

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

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

Generates the public/private key pair from the init params

Throws:
  `java.lang.Exception`

#### reset

    public void reset()

Just remove if you don't need to reset any state

#### up

    public java.lang.Object up(Event evt)

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`

#### passItUp

    public java.lang.Object passItUp(Event evt)

#### down

    public java.lang.Object down(Event evt)

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`

#### passItDown

    public java.lang.Object passItDown(Event evt)

#### getAsymInit

    protected int getAsymInit()

Returns:
  Returns the asymInit.

#### getAsymProvider

    protected java.lang.String getAsymProvider()

Returns:
  Returns the asymProvider.

#### getDesKey

    protected javax.crypto.SecretKey getDesKey()

Returns:
  Returns the desKey.

#### getKpair

    protected java.security.KeyPair getKpair()

Returns:
  Returns the kpair.

#### getAsymCipher

    protected javax.crypto.Cipher getAsymCipher()

Returns:
  Returns the asymCipher.

#### getServerPubKey

    protected java.security.PublicKey getServerPubKey()

Returns:
  Returns the serverPubKey.

#### getSymAlgorithm

    protected java.lang.String getSymAlgorithm()

Returns:
  Returns the symAlgorithm.

#### getSymInit

    protected int getSymInit()

Returns:
  Returns the symInit.

#### getSymProvider

    protected java.lang.String getSymProvider()

Returns:
  Returns the symProvider.

#### getAsymAlgorithm

    protected java.lang.String getAsymAlgorithm()

Returns:
  Returns the asymAlgorithm.

#### getKeyStoreName

    protected java.lang.String getKeyStoreName()

Returns:
  Returns the keyStoreName.

#### getSymDecodingCipher

    protected javax.crypto.Cipher getSymDecodingCipher()

Returns:
  Returns the symDecodingCipher.

#### getSymEncodingCipher

    protected javax.crypto.Cipher getSymEncodingCipher()

Returns:
  Returns the symEncodingCipher.

#### getLocal_addr

    protected Address getLocal_addr()

Returns:
  Returns the local_addr.

#### setLocal_addr

    protected void setLocal_addr(Address local_addr)

Parameters:
  `local_addr` - The local_addr to set.

#### getKeyServerAddr

    protected Address getKeyServerAddr()

Returns:
  Returns the keyServerAddr.

#### setKeyServerAddr

    protected void setKeyServerAddr(Address keyServerAddr)

Parameters:
  `keyServerAddr` - The keyServerAddr to set.