Debian Codegraph @

doc/ENCRYPT.html

raw
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>&nbsp;
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>&nbsp;
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 &lt;ENCRYPT key_store_name="defaultStore.keystore" store_password="changeit" alias="myKey"/&gt;<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>