> > > # Encryption Protocol Document

(Author : Mandar Shinde)

# Introduction

This document is required to be read by both the developers and the users. The
ENCRYPT protocol will not work by directly compiling the javagroups source
and then using the required "encrypt.xml" file. Since an external provider needs
to be used (JDK1.4 does not provider for RSA as of now), hence this provider
needs to be added to the users/developers security list.

# Installation

The following steps need to be followed to make sure that ENCRYPT protocol
can ne used

- Make sure that JDK1.4 is installed, ENCRYPT will not work with any other
  version under JDK1.4.
- After installation JDK1.4, set $JAVA_HOME to the installation root.
- cd $JAVA_HOME/jre/lib/security. Open java.security file.
- Search for security.provider.{list} in the opened file.
- At the end of the list add Provider.{list+1}=org.bouncycastle.jce.provider.BouncyCastleProvider.
- The above provider is the default provider that comes along with Javagroups;
  users can use their own providers by adding the right provider jars in the classpath
  and adding the provider to the required list.
- The encrypt.xml file is the default configuration on top of default.xml. Any stack can use the
  Encrypt protocol by adding this stack below GMS.
  <protocol>
<protocol-name> Encryption Protocol </protocol-name>
<description> Protocol provides encryption to all communication </description>
<class-name>org.jgroups.protocols.ENCRYPT1_4</class-name>
<protocol-params>
<protocol-param name="asymInit" value="512"/>
<protocol-param name="symInit" value="56"/>
<protocol-param name="asymAlgorithm" value="RSA"/>
<protocol-param name="symAlgorithm" value="DES/ECB/PKCS5Padding"/>
</protocol-params>
</protocol>

# Demo

To test the usage of the protocol use any demo; I have used the Draw demo for this purpose;.

- First up uncomment the Print protocol and comment the Encrypt protocol from the
  encrypt.xml file. When the Draw demo is used, the user will see the deserialized
  messages being exchanged between the 2 members.
- Now, uncomment the Encrypt protocol (leave the Print Protocol intact) from the protocol
  stack. Run the same demo as above; the user will see that an ioexception will thrown while
  deserializing the message because it has been encrypted by the Encrypt protocol.

# How does Encrypt protocol work ?

The mechanism used by this protocol is the oldest know way for high performing peer communication
protocols. To understand the working a couple algos need to be detailed; these are very basic in
today's encryption world.
Asymmetric algo: this algo uses a set of keys; a public-key and a private-key. The public-key is
public; it is published to the public. The private-key is known only to the entity which makes the
public-key available. Any other entity will encrypt a message using the former public-key and the
former will decrypt the message using the private-key.
Symmetric algo: this algo is the simplest known where a set of communication peers know a single
shared secret-key(private-key) and ecrypt/decrypt messages to communicate with each other.
Final algo : It is obvious that the asym algo seems more powerful than the symm algo. But, the asym
algorithm is very expensive and the symm algorithm has a basic fault on how to distribute the key. A
combination where the asym algo is used only for handshake and distribute the shared key is the best bet.
Only when a member leaves does it require to re-generate a shared key.

# Step-by-Step

1. The first-member in the group becomes the admin and generates the shared-key.
2. When a new peer requests to join, the new-member publishes its public-key.
3. Using the public-key the admin encodes its shared-key.
4. Using its own private-key, client decodes the shared-key.
5. New member lets the admin know, it is ready.
6. Members use shared-key to encrypt/decrypt messages.
7. When member leaves, admin regenerates shared-key. If admin leaves, another member becomes admin
   and regenerates key.