| 1 |
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
| 2 |
<html> |
| 3 |
<head> |
| 4 |
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| 5 |
</head> |
| 6 |
<body> |
| 7 |
|
| 8 |
<blockquote> |
| 9 |
<blockquote> |
| 10 |
<blockquote> |
| 11 |
<h1> |
| 12 |
<b>Encryption Protocol Document</b></h1> |
| 13 |
</blockquote> |
| 14 |
</blockquote> |
| 15 |
</blockquote> |
| 16 |
<b>(Author : Steve Woodcock)</b> |
| 17 |
<h1> |
| 18 |
<b>Introduction</b></h1> |
| 19 |
The encryption protocol provides encryption of messages in JGroups that are generated by applications. |
| 20 |
There are a few requirements in order to make use of the Encryption layer. |
| 21 |
<ul> |
| 22 |
<li> A suitable Security provider is required. (see security provider instructions later) |
| 23 |
<li> The java.security properties need to be configured (see installation guide). |
| 24 |
</ul> |
| 25 |
|
| 26 |
<br> |
| 27 |
The Encrypt layer can be used in one of two ways (the options are mutually exclusive so all participants in a JGroup must have the same settings). |
| 28 |
<ul> |
| 29 |
<li> Option 1. Configured with a secretKey in a keystore so it can be used at any |
| 30 |
layer in JGroups without the need for a coordinator, or if you want protection against passive |
| 31 |
monitoring but do not want the key exchange overhead and complexity. In this mode all nodes must be distributed with |
| 32 |
the same keystore file. <b>Due to issues with Sun's JCE you cannot use this option with JDK1.3</b> |
| 33 |
<p> |
| 34 |
<li> Option 2. Configured with only algorithms and key sizes. The Encrypt Layer in this mode should be used between the |
| 35 |
FRAG and PBCast layers in the stack. The coordinator chooses the |
| 36 |
secretkey which it distributes amongst all the peers. In this form no keystore exists as the keys are |
| 37 |
the key is generated and distributed by the controller using a public/private key exchange. View changes that identify a new controller will result in a new session key |
| 38 |
being generated and then distributed to all peers. This overhead can be substantial in a an application with |
| 39 |
a reasonable peer churn. |
| 40 |
</ul> |
| 41 |
<h1> |
| 42 |
<b>Installation</b></h1> |
| 43 |
The following steps need to be followed to make sure that ENCRYPT protocol can be used |
| 44 |
<br> |
| 45 |
<h2>Installing a Security Provider</h2> |
| 46 |
|
| 47 |
First you need to download an appropriate security provider. A good option is an organisation called bouncycastle, who |
| 48 |
provide an open-source clean room implementation of the JCE. You can find them at www.bouncycastle.org.<br> |
| 49 |
You must download the correct jar file for the JDK you are using - at the time of writing |
| 50 |
the 1.3 version is: jce-jdk13-124.jar and the 1.4 version is: bcprov-jdk14-124.jar. <br> |
| 51 |
You do not have to use the bouncycastle provider - others available include those from Phaos Technology, |
| 52 |
RSA and Wedgetail Communications. See the appropriate documentation for each provider. |
| 53 |
<p> |
| 54 |
If you are using 1.3 you must also install the SUN JCE provider (current version 1.2.2) to give access to the JCEKS keystore |
| 55 |
formats. This can be downloaded from the www.javasoft.com site. The following instructions are for JDK1.3 and 1.4.<p> |
| 56 |
|
| 57 |
|
| 58 |
Assuming <b>$JAVA_HOME</b> to be the JDK the installation root.<p> |
| 59 |
|
| 60 |
|
| 61 |
<h3>JDK 1.3</h3> |
| 62 |
Download the SunJCE file.<br> |
| 63 |
Unzip the file and place the jar files contained in the jce/lib folder in the |
| 64 |
<b>$JAVA_HOME/jre/lib/ext </b>directory<br> |
| 65 |
|
| 66 |
|
| 67 |
Place the bouncycastle provider in the <b>$JAVA_HOME/jre/lib/ext</b> directory.<p> |
| 68 |
|
| 69 |
Next configure the security file to add the new providers. |
| 70 |
<ul> |
| 71 |
<li>Open the <b>java.security</b> file in <b>$JAVA_HOME/jre/lib/security</b>.</li> |
| 72 |
|
| 73 |
<li> |
| 74 |
Search for <b>security.provider.{list}</b> in the opened file.</li> |
| 75 |
|
| 76 |
<li> |
| 77 |
Add the SunJCE provider as provider 2, and |
| 78 |
add the bouncycastle provider as the last.<br> |
| 79 |
</li> |
| 80 |
<li> |
| 81 |
You should end up with the entries similar to that shown below. |
| 82 |
<br> |
| 83 |
security.provider.1=sun.security.provider.Sun<br> |
| 84 |
security.provider.2=com.sun.crypto.provider.SunJCE<br> |
| 85 |
security.provider.3=com.sun.rsajca.Provider<br> |
| 86 |
security.provider.4=org.bouncycastle.jce.provider.BouncyCastleProvider<br> |
| 87 |
</li> |
| 88 |
</ul> |
| 89 |
|
| 90 |
<h3>JDK 1.4</h3> |
| 91 |
The JDK1.4 already includes the SunJCE files, so you only need to configure the bouncycastle provider.<br> |
| 92 |
|
| 93 |
|
| 94 |
Place the bouncycastle provider in the $JAVA_HOME/jre/lib/ext directory.<p> |
| 95 |
|
| 96 |
Next configure the security file to add the new providers. |
| 97 |
<ul> |
| 98 |
<li>Open the <b>java.security</b> file in <b>$JAVA_HOME/jre/lib/security</b>.</li> |
| 99 |
|
| 100 |
<li> |
| 101 |
Search for <b>security.provider.{list}</b> in the opened file.</li> |
| 102 |
|
| 103 |
<li> |
| 104 |
Add the bouncycastle provider as the last.<br> |
| 105 |
</li> |
| 106 |
<li> |
| 107 |
You should end up with similar entries as shown below. |
| 108 |
<br> |
| 109 |
security.provider.1=sun.security.provider.Sun<br> |
| 110 |
security.provider.2=com.sun.net.ssl.internal.ssl.Provider<br> |
| 111 |
security.provider.3=com.sun.rsajca.Provider<br> |
| 112 |
security.provider.4=com.sun.crypto.provider.SunJCE<br> |
| 113 |
security.provider.5=sun.security.jgss.SunProvider<br> |
| 114 |
security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider<br> |
| 115 |
</li> |
| 116 |
</ul> |
| 117 |
<h2>Configure the Encrypt Protocol</h2> |
| 118 |
|
| 119 |
<h2>Option 1 - Using a shared keystore (JDK1.4 Only)</h2><br> |
| 120 |
This is the simplest option and can be used by simply inserting the Encryption layer |
| 121 |
at any point in the JGroup stack - it will encrypt all Events of a type MSG that |
| 122 |
have a non-null message buffer. The format of the JGroup XML entry in this form is:<p> |
| 123 |
<b> |
| 124 |
<ENCRYPT key_store_name="defaultStore.keystore" store_password="changeit" alias="myKey"/><br> |
| 125 |
</b><p> |
| 126 |
An example bare-bones.xml file showing the keystore version can be found in the conf |
| 127 |
directory in a file called <b>EncryptKeyStore.xml</b> - you will need to generate a keystore - see the KeyStoreGenerator file in the demo directory or use the makeKeystore target in the build file.<br> |
| 128 |
In order to use the Encrypt layer in this manner it is necessary to have the secretKey already generated |
| 129 |
in a keystore file. The directory containing the keystore file must be on the application's classpath. |
| 130 |
You cannot create a SecretKey keystore file using the keytool application shipped with the JDK. |
| 131 |
A java file called KeyStoreGenerator is included in the demo |
| 132 |
package that can be used from the command line (or IDE) to generate a suitable keystore. |
| 133 |
<p> |
| 134 |
<b>IMPORTANT- A keystore generated under each version of the 1.4 JDK can be incompatible with other JDK versions. |
| 135 |
Make sure you generate the keystore with the same JDK version as you are going to use at runtime. This is important for 1.4.2_04 and 1.4.2_05.</b><p> |
| 136 |
|
| 137 |
<h2>Option 2 - Dynamic Key Generation (JDK1.3/1.4)</h2><br> |
| 138 |
This option is suited to an application that does not ship with a shared key but instead it is generated |
| 139 |
and distributed by the controller. The secret key is first generated by the Controller (in JGroup terms). When a view change |
| 140 |
occurs a peer will request the secret key by sending a key request with its own public key. The controller |
| 141 |
encrypts the secret key with this key and sends it back to the peer who then decrypts it and installs the |
| 142 |
key as its own secret key. |
| 143 |
<br>All encryption and decryption of Messages is done using this key. When a peer receives |
| 144 |
a view change that shows a different keyserver it will repeat this process - the view change event |
| 145 |
also trigger the encrypt layer to queue up and down messages until the new key is installed. |
| 146 |
The previous keys are retained so that messages sent before the view change that are queued can be decrypted |
| 147 |
if the key is different. |
| 148 |
<br> |
| 149 |
An example <b>EncryptNoKeyStore.xml</b> is included in the conf directory as a guide. |
| 150 |
<p><p> |
| 151 |
<br> Note: the current version does not support the concept of perfect forward encryption (PFE) |
| 152 |
which means that if a peer leaves the group, the keys are re-generated preventing the departed peer from |
| 153 |
decrypting future messages if it chooses to listen in on the group. This is not included as it really requires |
| 154 |
a suitable authentication scheme as well to make this feature useful as there is nothing to stop the peer rejoining and receiving the new |
| 155 |
key. A future release will address this issue. |
| 156 |
|
| 157 |
<h1> |
| 158 |
<b>Demo</b></h1> |
| 159 |
To test the usage of the protocol use any demo and change the xml config file to include the encrypt protocol. |
| 160 |
|
| 161 |
Starting up an application using the keystore option will result in an output similar to: |
| 162 |
<p> |
| 163 |
<blockquote> |
| 164 |
04-Aug-2004 21:11:38 org.jgroups.protocols.ENCRYPT setProperties<br> |
| 165 |
INFO: key_store_name used is defaultStore1_4.keystore<br> |
| 166 |
04-Aug-2004 21:11:38 org.jgroups.protocols.ENCRYPT setProperties<br> |
| 167 |
INFO: store_password used is not null<br> |
| 168 |
04-Aug-2004 21:11:39 org.jgroups.protocols.ENCRYPT setProperties<br> |
| 169 |
INFO: key_password used is same as store_password<br> |
| 170 |
04-Aug-2004 21:11:39 org.jgroups.protocols.ENCRYPT setProperties<br> |
| 171 |
INFO: alias used is myKey<br> |
| 172 |
04-Aug-2004 21:11:39 org.jgroups.protocols.ENCRYPT initSymCiphers<br> |
| 173 |
INFO: Initializing symmetric ciphers<br> |
| 174 |
04-Aug-2004 21:11:39 org.jgroups.protocols.ENCRYPT initSymCiphers<br> |
| 175 |
INFO: Initialized symmetric ciphers with secret key version �;ٺ�8=fԱ;qe2�<br> |
| 176 |
</blockquote> |
| 177 |
If you want to confirm the encryption/decryption messages then set the logging level to debug |
| 178 |
for the protocol. |
| 179 |
|
| 180 |
<p> |
| 181 |
If you are using the encryption without a keystore you should see output similar to: |
| 182 |
<blockquote> |
| 183 |
05-Aug-2004 13:43:52 org.jgroups.protocols.ENCRYPT initSymKey<br> |
| 184 |
INFO: Symmetric key generated<br> |
| 185 |
05-Aug-2004 13:43:53 org.jgroups.protocols.ENCRYPT initKeyPair<br> |
| 186 |
INFO: asym algo initialized<br> |
| 187 |
05-Aug-2004 13:43:53 org.jgroups.protocols.ENCRYPT initSymCiphers<br> |
| 188 |
INFO: Initializing symmetric ciphers<br> |
| 189 |
05-Aug-2004 13:43:53 org.jgroups.protocols.ENCRYPT initSymCiphers<br> |
| 190 |
INFO: Initialized symmetric ciphers with secret key version �~6��Ɨ/h%ڤĹ<br> |
| 191 |
................<br> |
| 192 |
Later in the output you should see logging identifying that the JGroups peer has become the |
| 193 |
keyServer - this will be the same peer that is the group coordinator.<p> |
| 194 |
05-Aug-2004 13:43:55 org.jgroups.protocols.ENCRYPT up<br> |
| 195 |
INFO: handling view change event<br> |
| 196 |
05-Aug-2004 13:43:55 org.jgroups.protocols.ENCRYPT becomeKeyServer<br> |
| 197 |
INFO: I have become key server<br> |
| 198 |
|
| 199 |
</blockquote> |
| 200 |
<p> |
| 201 |
Note: the key version is an MD5 hash of the key in an encoded form from which you cannot get |
| 202 |
the original key data. |
| 203 |
</body> |
| 204 |
</html> |