Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> jgroups >> [ protocols overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

org.jgroups.protocols
Class ENCRYPT  

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

---

public class ENCRYPT

extends org.jgroups.stack.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.

---

Nested Class Summary
static class	ENCRYPT.EncryptHeader

 

Field Summary
private  java.lang.String	alias
(package private)  java.lang.String	asymAlgorithm
private  javax.crypto.Cipher	asymCipher
(package private)  int	asymInit
(package private)  java.lang.String	asymProvider
(package private)  java.lang.Object	downLock
private  EDU.oswego.cs.dl.util.concurrent.LinkedQueue	downMessageQueue
(package private)  java.util.Map	keyMap
private  java.lang.String	keyPassword
(package private)  boolean	keyServer
(package private)  org.jgroups.Address	keyServerAddr
private  java.lang.String	keyStoreName
(package private)  java.security.KeyPair	Kpair
(package private)  org.jgroups.Address	local_addr
private  boolean	queue_down
private  boolean	queue_up
(package private)  javax.crypto.SecretKey	secretKey
(package private)  java.security.PublicKey	serverPubKey
private  java.lang.String	storePassword
private  boolean	suppliedKey
(package private)  java.lang.String	symAlgorithm
(package private)  javax.crypto.Cipher	symDecodingCipher
(package private)  javax.crypto.Cipher	symEncodingCipher
(package private)  int	symInit
(package private)  java.lang.String	symProvider
private  java.lang.String	symVersion
(package private)  java.lang.Object	upLock
private  EDU.oswego.cs.dl.util.concurrent.LinkedQueue	upMessageQueue

 

Fields inherited from class org.jgroups.stack.Protocol

down_handler, down_prot, down_queue, down_thread, down_thread_prio, log, observer, props, stack, stats, trace, up_handler, up_prot, up_queue, up_thread, up_thread_prio, warn

 

Constructor Summary

ENCRYPT()

 

Method Summary
private  void	becomeKeyServer(org.jgroups.Address tmpKeyServer)           Handles becoming server - resetting queue settings and setting keyserver address to be local address.
private  javax.crypto.spec.SecretKeySpec	decodeKey(byte[] encodedKey)
private  org.jgroups.Message	decryptMessage(javax.crypto.Cipher cipher, org.jgroups.Message msg)           Does the actual work for decrypting - if version does not match current cipher then tries to use previous cipher
void	down(org.jgroups.Event evt)           An event is to be sent down the stack.
private  void	drainDownQueue()
private  void	drainUpQueue()           used to drain the up queue - synchronized so we can call it safely despite access from potentially two threads at once
private  byte[]	encryptMessage(javax.crypto.Cipher cipher, byte[] plain)
private  java.lang.String	formatArray(byte[] array)
private  java.security.PublicKey	generatePubKey(byte[] encodedKey)           used to reconstitute public key sent in byte form from peer
private  java.lang.String	getAlgorithm(java.lang.String s)
protected  java.lang.String	getAsymAlgorithm()
protected  javax.crypto.Cipher	getAsymCipher()
protected  int	getAsymInit()
protected  java.lang.String	getAsymProvider()
protected  javax.crypto.SecretKey	getDesKey()
protected  org.jgroups.Address	getKeyServerAddr()
protected  java.lang.String	getKeyStoreName()
protected  java.security.KeyPair	getKpair()
protected  org.jgroups.Address	getLocal_addr()
java.lang.String	getName()
private  javax.crypto.SecretKey	getSecretKey()
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()
private  java.lang.String	getSymVersion()
private  void	handleDownEvent(org.jgroups.Event evt)           handle method for down mesages
private  java.security.PublicKey	handleKeyRequest(org.jgroups.Message msg)
private  void	handleNewKeyServer(org.jgroups.Address newKeyServer)           Sets up the peer for a new keyserver - this is setting queueing to buffer messages until we have a new secret key from the key server and sending a key request to the new keyserver.
private  void	handleUpMessage(org.jgroups.Event evt)
private  void	handleViewChange(org.jgroups.Event evt)
void	init()           Called after instance has been created (null constructor) and before protocol is started.
private  void	initConfiguredKey()           Initialisation if a supplied key is defined in the properties.
void	initKeyPair()           Generates the public/private key pair from the init params
private  void	initSymCiphers(java.lang.String algorithm, javax.crypto.SecretKey secret)           Initialises the Ciphers for both encryption and decryption using the generated or supplied secret key.
void	initSymKey()           Used to initialise the symmetric key if none is supplied in a keystore.
void	reset()           Just remove if you don't need to reset any state
private  void	sendDown(org.jgroups.Event evt)
private  org.jgroups.Message	sendKeyRequest()
private  void	sendSecretKey(javax.crypto.SecretKey secret, java.security.PublicKey pubKey, org.jgroups.Address source)
private  void	setKeys(javax.crypto.SecretKey key, java.lang.String version)           Sets the keys for the app.
protected  void	setKeyServerAddr(org.jgroups.Address keyServerAddr)
protected  void	setLocal_addr(org.jgroups.Address local_addr)
boolean	setProperties(java.util.Properties props)           Configures the protocol initially.
private  void	setSecretKey(javax.crypto.SecretKey secretKey)
private  void	setServerPubKey(java.security.PublicKey serverPubKey)
private  void	setSymVersion(java.lang.String symVersion)
void	up(org.jgroups.Event evt)           An event was received from the layer below.

 

Methods inherited from class org.jgroups.stack.Protocol

destroy, downThreadEnabled, dumpStats, enableStats, getDownProtocol, getDownQueue, getProperties, getUpProtocol, getUpQueue, handleSpecialDownEvent, isTrace, isWarn, passDown, passUp, printStats, providedDownServices, providedUpServices, receiveDownEvent, receiveUpEvent, requiredDownServices, requiredUpServices, resetStats, setDownProtocol, setObserver, setPropertiesInternal, setProtocolStack, setTrace, setUpProtocol, setWarn, start, startDownHandler, startUpHandler, statsEnabled, stop, stopInternal, upThreadEnabled

 

Methods inherited from class java.lang.Object

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

 

Field Detail

local_addr

org.jgroups.Address local_addr

---

keyServerAddr

org.jgroups.Address keyServerAddr

---

keyServer

boolean keyServer

---

asymProvider

java.lang.String asymProvider

---

symProvider

final java.lang.String symProvider

---

asymAlgorithm

java.lang.String asymAlgorithm

---

symAlgorithm

java.lang.String symAlgorithm

---

asymInit

int asymInit

---

symInit

int symInit

---

suppliedKey

private boolean suppliedKey

---

keyStoreName

private java.lang.String keyStoreName

---

storePassword

private java.lang.String storePassword

---

keyPassword

private java.lang.String keyPassword

---

alias

private java.lang.String alias

---

Kpair

java.security.KeyPair Kpair

---

serverPubKey

java.security.PublicKey serverPubKey

---

symEncodingCipher

javax.crypto.Cipher symEncodingCipher

---

symDecodingCipher

javax.crypto.Cipher symDecodingCipher

---

symVersion

private java.lang.String symVersion

---

secretKey

javax.crypto.SecretKey secretKey

---

keyMap

final java.util.Map keyMap

---

downLock

final java.lang.Object downLock

---

upLock

final java.lang.Object upLock

---

queue_up

private boolean queue_up

---

queue_down

private boolean queue_down

---

upMessageQueue

private EDU.oswego.cs.dl.util.concurrent.LinkedQueue upMessageQueue

---

downMessageQueue

private EDU.oswego.cs.dl.util.concurrent.LinkedQueue downMessageQueue

---

asymCipher

private javax.crypto.Cipher asymCipher

Constructor Detail

ENCRYPT

public ENCRYPT()

Method Detail

getName

public java.lang.String getName()

---

getAlgorithm

private java.lang.String getAlgorithm(java.lang.String s)

---

setProperties

public boolean setProperties(java.util.Properties props)

Description copied from class: org.jgroups.stack.Protocol

Configures the protocol initially. A configuration string consists of name=value items, separated by a ';' (semicolon), e.g.:

 "loopback=false;unicast_inport=4444"
 

---

init

public void init()
          throws java.lang.Exception

Description copied from class: org.jgroups.stack.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.

---

initConfiguredKey

private void initConfiguredKey()
                        throws java.security.KeyStoreException,
                               java.lang.Exception,
                               java.io.IOException,
                               java.security.NoSuchAlgorithmException,
                               java.security.cert.CertificateException,
                               java.security.UnrecoverableKeyException

Initialisation if a supplied key is defined in the properties. This supplied key must be in a keystore which can be generated using the keystoreGenerator file in demos. The keystore must be on the classpath to find it.

---

initSymKey

public void initSymKey()
                throws java.lang.Exception

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

---

initSymCiphers

private void initSymCiphers(java.lang.String algorithm,
                            javax.crypto.SecretKey secret)
                     throws java.lang.Exception

Initialises the Ciphers for both encryption and decryption using the generated or supplied secret key.

---

initKeyPair

public void initKeyPair()
                 throws java.lang.Exception

Generates the public/private key pair from the init params

---

reset

public void reset()

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

---

up

public void up(org.jgroups.Event evt)

Description copied from class: org.jgroups.stack.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 passDown() or c) the event (or another event) is sent up the stack using passUp().

---

handleViewChange

private void handleViewChange(org.jgroups.Event evt)

---

becomeKeyServer

private void becomeKeyServer(org.jgroups.Address tmpKeyServer)

Handles becoming server - resetting queue settings and setting keyserver address to be local address.

---

handleNewKeyServer

private void handleNewKeyServer(org.jgroups.Address newKeyServer)

Sets up the peer for a new keyserver - this is setting queueing to buffer messages until we have a new secret key from the key server and sending a key request to the new keyserver.

---

handleUpMessage

private void handleUpMessage(org.jgroups.Event evt)
                      throws java.lang.Exception

---

drainUpQueue

private void drainUpQueue()
                   throws org.jgroups.util.QueueClosedException,
                          java.lang.Exception

used to drain the up queue - synchronized so we can call it safely despite access from potentially two threads at once

---

setKeys

private void setKeys(javax.crypto.SecretKey key,
                     java.lang.String version)
              throws java.lang.Exception

Sets the keys for the app. and drains the queues - the drains could be called att he same time as the up/down messages calling in to the class so we may have an extra call to the drain methods but this slight expense is better than the alternative of waiting until the next message to trigger the drains which may never happen.

---

decryptMessage

private org.jgroups.Message decryptMessage(javax.crypto.Cipher cipher,
                                           org.jgroups.Message msg)
                                    throws java.lang.Exception

Does the actual work for decrypting - if version does not match current cipher then tries to use previous cipher

---

sendSecretKey

private void sendSecretKey(javax.crypto.SecretKey secret,
                           java.security.PublicKey pubKey,
                           org.jgroups.Address source)
                    throws java.security.InvalidKeyException,
                           java.lang.IllegalStateException,
                           javax.crypto.IllegalBlockSizeException,
                           javax.crypto.BadPaddingException,
                           javax.crypto.NoSuchPaddingException,
                           java.security.NoSuchAlgorithmException

---

handleKeyRequest

private java.security.PublicKey handleKeyRequest(org.jgroups.Message msg)

---

sendKeyRequest

private org.jgroups.Message sendKeyRequest()

---

down

public void down(org.jgroups.Event evt)

Description copied from class: org.jgroups.stack.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 passDown(). 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 passUp().

---

handleDownEvent

private void handleDownEvent(org.jgroups.Event evt)
                      throws java.lang.Exception

handle method for down mesages

---

drainDownQueue

private void drainDownQueue()
                     throws java.lang.Exception,
                            org.jgroups.util.QueueClosedException

---

sendDown

private void sendDown(org.jgroups.Event evt)
               throws java.lang.Exception

---

encryptMessage

private byte[] encryptMessage(javax.crypto.Cipher cipher,
                              byte[] plain)
                       throws java.lang.Exception

---

decodeKey

private javax.crypto.spec.SecretKeySpec decodeKey(byte[] encodedKey)
                                           throws java.lang.Exception

---

generatePubKey

private java.security.PublicKey generatePubKey(byte[] encodedKey)

used to reconstitute public key sent in byte form from peer

---

formatArray

private java.lang.String formatArray(byte[] array)

---

getAsymInit

protected int getAsymInit()

---

getAsymProvider

protected java.lang.String getAsymProvider()

---

getDesKey

protected javax.crypto.SecretKey getDesKey()

---

getKpair

protected java.security.KeyPair getKpair()

---

getAsymCipher

protected javax.crypto.Cipher getAsymCipher()

---

getServerPubKey

protected java.security.PublicKey getServerPubKey()

---

getSymAlgorithm

protected java.lang.String getSymAlgorithm()

---

getSymInit

protected int getSymInit()

---

getSymProvider

protected java.lang.String getSymProvider()

---

getAsymAlgorithm

protected java.lang.String getAsymAlgorithm()

---

getSymVersion

private java.lang.String getSymVersion()

---

setSymVersion

private void setSymVersion(java.lang.String symVersion)

---

getSecretKey

private javax.crypto.SecretKey getSecretKey()

---

setSecretKey

private void setSecretKey(javax.crypto.SecretKey secretKey)

---

setServerPubKey

private void setServerPubKey(java.security.PublicKey serverPubKey)

---

getKeyStoreName

protected java.lang.String getKeyStoreName()

---

getSymDecodingCipher

protected javax.crypto.Cipher getSymDecodingCipher()

---

getSymEncodingCipher

protected javax.crypto.Cipher getSymEncodingCipher()

---

getLocal_addr

protected org.jgroups.Address getLocal_addr()

---

setLocal_addr

protected void setLocal_addr(org.jgroups.Address local_addr)

---

getKeyServerAddr

protected org.jgroups.Address getKeyServerAddr()

---

setKeyServerAddr

protected void setKeyServerAddr(org.jgroups.Address keyServerAddr)

---

Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> jgroups >> [ protocols overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---