org.jgroups.protocols

Class ASYM_ENCRYPT

java.lang.Object

org.jgroups.stack.Protocol

org.jgroups.protocols.EncryptBase

org.jgroups.protocols.ASYM_ENCRYPT

public class ASYM_ENCRYPT
extends EncryptBase

Encrypts and decrypts communication in JGroups by using a secret key distributed to all cluster members by the key server (coordinator) using asymmetric (public/private key) encryption.
The secret key is identical for all cluster members and is used to encrypt messages when sending and decrypt them when receiving messages. This protocol is typically placed under NAKACK2, so that most important headers are encrypted as well, to prevent replay attacks.
The current keyserver (always the coordinator) generates a secret key. When a new member joins, it asks the keyserver for the secret key. The keyserver encrypts the secret key with the joiner's public key and the joiner decrypts it with its private key and then installs it and starts encrypting and decrypting messages with the secret key.
View changes that identify a new keyserver will result in a new secret key being generated and then distributed to all cluster members. This overhead can be substantial in an application with a reasonable member churn.
This protocol is suited to an application that does not ship with a known key but instead it is generated and distributed by the keyserver. Since messages can only get encrypted and decrypted when the secret key was received from the keyserver, messages other then join and merge requests/responses are dropped when the secret key isn't yet available. Join and merge requests / responses are handled by AUTH.

Author:

Bela Ban, Steve Woodcock

Nested Class Summary

Nested classes/interfaces inherited from class org.jgroups.protocols.EncryptBase

EncryptBase.Decrypter

Field Summary

Fields

Modifier and Type	Field and Description
protected javax.crypto.Cipher	asym_cipher
protected boolean	change_key_on_leave
protected static short	GMS_ID
protected java.security.KeyPair	key_pair
protected ResponseCollectorTask<java.lang.Boolean>	key_requesters
protected Address	key_server_addr
protected long	key_server_interval
protected long	last_key_request
protected long	min_time_between_key_requests
protected java.util.concurrent.locks.Lock	queue_lock
protected boolean	queue_up_msgs
protected java.util.concurrent.BlockingQueue<Message>	up_queue
protected boolean	use_external_key_exchange

Fields inherited from class org.jgroups.protocols.EncryptBase

asym_algorithm, asym_keylength, cipher_pool_size, decoding_ciphers, DEFAULT_SYM_ALGO, encoding_ciphers, encrypt_entire_message, key_map, key_map_max_size, local_addr, provider, secret_key, sign_msgs, sym_algorithm, sym_keylength, sym_version, use_adler, view

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
ASYM_ENCRYPT()

Method Summary

Modifier and Type	Method and Description
javax.crypto.Cipher	asymCipher()
protected void	createNewKey()
protected javax.crypto.SecretKey	createSecretKey() Initialise the symmetric key if none is supplied in a keystore
protected javax.crypto.spec.SecretKeySpec	decodeKey(byte[] encodedKey)
java.lang.Object	down(Event evt) An event is to be sent down the stack.
protected byte[]	encryptSecretKey(java.security.Key secret_key, java.security.PublicKey public_key) Encrypts the current secret key with the requester's public key (the requester will decrypt it with its private key)
protected boolean	enqueue(Message msg)
protected java.security.PublicKey	generatePubKey(byte[] encodedKey) Used to reconstitute public key sent in byte form from peer
protected Address	getCoordinator(Message msg, GMS.GmsHeader hdr) Tries to find out if this is a JOIN_RSP or INSTALL_MERGE_VIEW message and returns the coordinator of the view
java.lang.String	getKeyServerAddress()
protected void	handleNewKeyServer(Address old_key_server, boolean merge_view, boolean left_mbrs) If the keyserver changed, send a request for the secret key to the keyserver
protected void	handleSecretKeyRequest(Message msg)
protected void	handleSecretKeyResponse(Message msg, byte[] key_version)
protected void	handleUnknownVersion(byte[] version) Called when the version shipped in the header can't be found
protected java.lang.Object	handleUpEvent(Message msg, EncryptHeader hdr)
protected void	handleView(View v)
void	init() Called after instance has been created (null constructor) and before protocol is started.
protected void	initKeyPair() Generates the public/private key pair from the init params
boolean	isKeyServer()
java.security.KeyPair	keyPair()
Address	keyServerAddr()
ASYM_ENCRYPT	keyServerAddr(Address key_srv)
protected boolean	keyServerChanged(Address old_keyserver)
long	minTimeBetweenKeyRequests()
ASYM_ENCRYPT	minTimeBetweenKeyRequests(long t)
protected boolean	process(Message msg) Whether or not to process this received message
java.util.List<java.lang.Integer>	providedDownServices() List of events that are provided to layers below (they will be handled when sent down below)
int	queueSize()
void	sendKeyRequest()
protected void	sendKeyRequest(Address key_server) send client's public key to server and request server's public key
protected void	sendNewKeyserverAck(Address dest)
protected void	sendSecretKey(java.security.Key secret_key, java.security.PublicKey public_key, Address source)
protected void	setKeys(javax.crypto.SecretKey key, byte[] version)
protected static boolean	skip(Message msg) Checks if a message needs to be encrypted/decrypted.
protected void	startQueueing()
void	stop() This method is called on a Channel.disconnect().
protected void	stopQueueing()
java.lang.Object	up(Event evt) An event was received from the layer below.
void	up(MessageBatch batch) Sends up a multiple messages in a MessageBatch.

Methods inherited from class org.jgroups.protocols.EncryptBase

_decrypt, adler, adler, asymAlgorithm, asymAlgorithm, asymKeylength, asymKeylength, code, computeChecksum, createChecksummer, createCipher, decryptChecksum, decryptMessage, encryptAndSend, encryptChecksum, encryptEntireMessage, encryptEntireMessage, getAlgorithm, handleEncryptedMessage, handleUpMessage, initSymCiphers, inView, localAddress, secretKey, secretKey, signMessages, signMessages, symAlgorithm, symAlgorithm, symKeylength, symKeylength, symVersion, symVersion, version

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, providedUpServices, requiredDownServices, requiredUpServices, resetStatistics, resetStats, setDownProtocol, setErgonomics, setId, setLevel, setProtocolStack, setSocketFactory, setUpProtocol, setValue, setValues, start, statsEnabled

Methods inherited from class java.lang.Object

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

Field Detail

GMS_ID

protected static final short GMS_ID

change_key_on_leave

protected boolean change_key_on_leave

use_external_key_exchange

protected boolean use_external_key_exchange

key_server_interval

protected long key_server_interval

key_server_addr

protected volatile Address key_server_addr

key_pair

protected java.security.KeyPair key_pair

asym_cipher

protected javax.crypto.Cipher asym_cipher

queue_lock

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

queue_up_msgs

protected boolean queue_up_msgs

up_queue

protected final java.util.concurrent.BlockingQueue<Message> up_queue

min_time_between_key_requests

protected long min_time_between_key_requests

last_key_request

protected volatile long last_key_request

key_requesters

protected ResponseCollectorTask<java.lang.Boolean> key_requesters

Constructor Detail

ASYM_ENCRYPT

public ASYM_ENCRYPT()

Method Detail

keyPair

public java.security.KeyPair keyPair()

asymCipher

public javax.crypto.Cipher asymCipher()

keyServerAddr

public Address keyServerAddr()

keyServerAddr

public ASYM_ENCRYPT keyServerAddr(Address key_srv)

minTimeBetweenKeyRequests

public long minTimeBetweenKeyRequests()

minTimeBetweenKeyRequests

public ASYM_ENCRYPT minTimeBetweenKeyRequests(long t)

providedDownServices

public java.util.List<java.lang.Integer> providedDownServices()

Description copied from class: Protocol

List of events that are provided to layers below (they will be handled when sent down below)

Overrides:

providedDownServices in class Protocol

queueSize

public int queueSize()

getKeyServerAddress

public java.lang.String getKeyServerAddress()

sendKeyRequest

public void sendKeyRequest()

isKeyServer

public boolean isKeyServer()

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 EncryptBase

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

stop

public void stop()

Description copied from class: Protocol

This method is called on a Channel.disconnect(). Stops work (e.g. by closing multicast socket). Will be called from top to bottom. This means that at the time of the method invocation the neighbor protocol below is still working. This method will replace the STOP, STOP_OK, CLEANUP and CLEANUP_OK events. The ProtocolStack guarantees that when this method is called all messages in the down queue will have been flushed

Overrides:

stop in class Protocol

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 EncryptBase

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 EncryptBase

up

public void up(MessageBatch batch)

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 EncryptBase

Parameters:

batch - The message batch

getCoordinator

protected Address getCoordinator(Message msg,
                                 GMS.GmsHeader hdr)

Tries to find out if this is a JOIN_RSP or INSTALL_MERGE_VIEW message and returns the coordinator of the view

skip

protected static boolean skip(Message msg)

Checks if a message needs to be encrypted/decrypted. Join and merge requests/responses don't need to be encrypted as they're authenticated by AUTH

handleUpEvent

protected java.lang.Object handleUpEvent(Message msg,
                                         EncryptHeader hdr)

Overrides:

handleUpEvent in class EncryptBase

process

protected boolean process(Message msg)

Description copied from class: EncryptBase

Whether or not to process this received message

Overrides:

process in class EncryptBase

handleSecretKeyRequest

protected void handleSecretKeyRequest(Message msg)

handleSecretKeyResponse

protected void handleSecretKeyResponse(Message msg,
                                       byte[] key_version)

createSecretKey

protected javax.crypto.SecretKey createSecretKey()
                                          throws java.lang.Exception

Initialise the symmetric key if none is supplied in a keystore

Throws:

java.lang.Exception

initKeyPair

protected void initKeyPair()
                    throws java.lang.Exception

Generates the public/private key pair from the init params

Throws:

java.lang.Exception

handleView

protected void handleView(View v)

Overrides:

handleView in class EncryptBase

createNewKey

protected void createNewKey()

handleNewKeyServer

protected void handleNewKeyServer(Address old_key_server,
                                  boolean merge_view,
                                  boolean left_mbrs)

If the keyserver changed, send a request for the secret key to the keyserver

keyServerChanged

protected boolean keyServerChanged(Address old_keyserver)

setKeys

protected void setKeys(javax.crypto.SecretKey key,
                       byte[] version)
                throws java.lang.Exception

Throws:

java.lang.Exception

sendSecretKey

protected void sendSecretKey(java.security.Key secret_key,
                             java.security.PublicKey public_key,
                             Address source)
                      throws java.lang.Exception

Throws:

java.lang.Exception

encryptSecretKey

protected byte[] encryptSecretKey(java.security.Key secret_key,
                                  java.security.PublicKey public_key)
                           throws java.lang.Exception

Encrypts the current secret key with the requester's public key (the requester will decrypt it with its private key)

Throws:

java.lang.Exception

sendKeyRequest

protected void sendKeyRequest(Address key_server)

send client's public key to server and request server's public key

sendNewKeyserverAck

protected void sendNewKeyserverAck(Address dest)

decodeKey

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

Throws:

java.lang.Exception

startQueueing

protected void startQueueing()

enqueue

protected boolean enqueue(Message msg)

stopQueueing

protected void stopQueueing()

handleUnknownVersion

protected void handleUnknownVersion(byte[] version)

Description copied from class: EncryptBase

Called when the version shipped in the header can't be found

Overrides:

handleUnknownVersion in class EncryptBase

generatePubKey

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

Used to reconstitute public key sent in byte form from peer