1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="subject" content="Apache SOAP and SMTP">
<meta name="GENERATOR" content="Mozilla/4.75 [en] (Windows NT 5.0; U) [Netscape]">
<title>Setting up Apache Tomcat and SOAP for SSL communication</title>
<!-- saved from url=(0022)http://internet.e-mail -->
<style type="text/css">
<!--
H1 { font-family : Arial, Helvetica; font-size : 14pt }
H2 { font-family : Arial, Helvetica; font-style: italic; font-size : 12pt }
H3 { font-family : Arial, Helvetica; font-size : 10pt }
CODE { font-family : Courier New, Courier; font-size : 9pt; color : #0000ff }
PRE { font-family : Courier New, Courier; font-size : 9pt; color : #0000ff }
-->
</style>
</head>
<body link="#0000FF" vlink="#800080">
<h1>
Setting up Apache Tomcat and a Simple Apache SOAP Client for SSL Communication.</h1>
<h3>
By <a href="mailto:glynnp@tcd.ie">Peter Glynn</a> and <a href="mailto:EB92401@jp.ibm.com">Darrell
Drake</a>, with minor updates by <a href="mailto:j_chawke@hotmail.com">Jonathan
Chawke</a>, April 2001.</h3>
<h2>
Introduction</h2>
This document gives steps involved in setting up Apache Tomcat and a simple
Apache SOAP client for <a href="http://developer.netscape.com/docs/manuals/security/sslin/contents.htm">SSL</a>
communication.
<br>The aim of this document is to allow a person with minimum Java security
to be able to set up SSL connection in a Apache SOAP/Tomcat Application.
The steps you will carry out are:
<ol TYPE="1">
<li>
Install the Java Secure Socket Extensions (JSSE) package (available from
Sun).</li>
<li>
Generate Client and Server Certificates for SSL communication.</li>
<ol TYPE="a">
<li>
Generate a Server Key and Certificate</li>
<li>
Export the Server Certificate</li>
<li>
Generate a Client Key and Certificate</li>
<li>
Export the Client Certificate</li>
<li>
Import the Certificates into the Keystores</li>
</ol>
<li>
Set up Tomcat for SSL Communication</li>
<li>
Modify the SOAP Client to use SSL</li>
</ol>
Also included in this document is:
<ul>
<li>
A short tutorial on creating X.509 Certificate Chains</li>
<li>
A section on troubleshooting SOAP and SSL installations</li>
</ul>
<h2>
Assumptions</h2>
It is assumed that you have installed <a href="http://xml.apache.org/soap">Apache
SOAP</a> and <a href="http://jakarta.apache.org/tomcat/">Apache Tomcat</a>,
and that the sample SOAP applications are working.
<h2>
Tools needed for Installation</h2>
<ul>
<li>
Apache SOAP download at <a href="http://xml.apache.org/dist/soap/">http://xml.apache.org/dist/soap/</a></li>
<li>
Java (tm) Secure Socket Extension (JSSE) 1.0.2 (jsse1.0.2) download at
<a href="http://java.sun.com/products/jsse/">http://java.sun.com/products/jsse/</a>
(free registration required)</li>
</ul>
<h2>
Step 1: Install JSSE</h2>
<ul>
<li>
Before you do anything, <b>read</b> the installation instructions for JSSE!
(they are available online at: <a href="http://java.sun.com/products/jsse/install.html">http://java.sun.com/products/jsse/install.html</a>).</li>
<li>
Add the JSSE jars to your classpath. This should hopefully add it to the
classpath of your Tomcat server. If not, add it to the classpath of the
Tomcat server or just copy the JSSE jar files to the lib directory of Tomcat
(e.g. <tt>C:\jakarta-tomcat-3.2.1\lib</tt>). This will automatically load
on start-up of Tomcat.</li>
<br>The JSSE 1.0.2 jars that you need in your classpath are:
<ul>
<li>
<tt>jsse.jar</tt></li>
<li>
<tt>jcert.jar</tt></li>
<li>
<tt>jnet.jar</tt></li>
</ul>
</ul>
<h2>
Step 2: Generate Client and Server Certificates</h2>
It is necessary to generate a Certificate for the client and the server.
These Certificates are then imported into a keystore, to which the client
and server connect.
<br>The keystore acts as a database for security certificates.
<br>You are going to use the <tt>keytool</tt> utility in the JDK to do
these tasks (see <a href="http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/keytool.html">Sun's
documentation</a> for more information on this tool).
<h3>
Step 2a: Generate a Server Key and Certificate</h3>
Launch <tt>keytool</tt> from a shell (or command prompt) to generate your
public and private key.
<br>Note that the Certificate and keystore files will be generated in the
directory you run <tt>keytool</tt> from.
<p>Use <tt>keytool</tt> as follows:
<br><tt>keytool -genkey -alias tomcat-sv -dname "CN=[Common Name],OU=[Organisation
Unit], O=[Organisation Name], L=[Locality], S=[State Name], C=[Two-Letter
Country Code]" -keyalg RSA -keypass [private key password] -storepass [keystore
password] -keystore [keystore file name]</tt>
<p>For example, to generate a keystore (in file <tt>server.keystore</tt>)
for server <tt>soapsvr.test.tcd.ie</tt> using password <tt>changeit</tt>
(for both the keystore and the certificate) in the Computer Engineering
group at Trinity College Dublin, Ireland, one would type the following:
<tt>keytool -genkey -alias tomcat-sv -dname "CN=soapsvr.test.tcd.ie, OU=ComputerEngineering,
O=Trinity College Dublin, L=Dublin, S=Dublin, C=IE" -keyalg RSA -keypass
changeit -storepass changeit -keystore server.keystore</tt>
<p>Note that
<ul>
<li>
The RSA algorithm is used to generate certificates.</li>
<li>
Ensure that the 'CN' field that you specify when you create the server
certificate matches the name of the machine on which you're running tomcat,
or your browser will complain about certificate name mis-matches (not a
problem on a test server, a big problem on a production server!).</li>
</ul>
<h3>
Step 2b: Export the Server Certificate</h3>
>From command prompt run this command to export your certificate from the
keystore into an external file (we do this so we can import the certificate
into the client's keystore as a trusted certificate).
<pre>
keytool -export -alias tomcat-sv -storepass changeit -file server.cer -keystore server.keystore
</pre>
If everything works, you should now have a file called <tt>server.cer</tt>
which contains your server's certificate.
<h3>
Step 2c: Generate a Client Key and Certificate</h3>
This step is very similar to the generation of the server key and certificate
- it uses the same <tt>keytool</tt> tool with different parameters.
<br>Note that the keystore file name has changed (it is now <tt>client.keystore</tt>).
Use <tt>keytool</tt> as follows:
<p><tt>keytool -genkey -alias tomcat-cl -dname "CN=Client,OU=TRL, O=IBM,
L=Yamato-shi, S=Kanagawa-ken, C=JP" -keyalg RSA -keypass changeit -storepass
changeit -keystore client.keystore</tt>
<h3>
Step 2d: Export the Client Certificate</h3>
This step is very similar to the export of the server certificate - it
uses the same <tt>keytool</tt> tool with different parameters:
<pre>
keytool -export -alias tomcat-cl -storepass changeit -file client.cer -keystore client.keystore
</pre>
If everything works, you should now have a file called <tt>client.cer</tt>
which contains your client's certificate.
<h3>
Step 2e: Import the Certificates into the Keystores</h3>
We want the client certificate to be added to the server's keystore, and
the server's certificate to be added to the client's keystore.
<br>Doing this will mean that the client and server trust one another.
<br>Import the server certificate into the client's keystore:
<br><tt>keytool -import -v -trustcacerts -alias tomcat -file server.cer
-keystore client.keystore -keypass changeit -storepass changeit</tt>
<br>Import the client certificate into the server's keystore: <tt>keytool
-import -v -trustcacerts -alias tomcat -file client.cer -keystore server.keystore
-keypass changeit -storepass changeit</tt>
<h2>
Step 3: Set up Tomcat for SSL Communication</h2>
<h3>
Step 3a: Modify your Tomcat Configuration File</h3>
You need to amend server.xml (located in the <tt>conf</tt> directory of
Apache Tomcat). Add the following lines to the xml file:
<pre>
<Connector className ="org.apache.tomcat.service.PoolTcpConnector">
<Parameter name="handler" value ="org.apache.tomcat.service.http.HttpConnectionHandler"/>
<Parameter name="port" value="8443"/>
<Parameter name="socketFactory" value="org.apache.tomcat.net.SSLSocketFactory" />
<b><Parameter name="keystore" value="c:\apache\soap-2_2\bin\server.keystore" />
</b><Parameter name="keypass" value="changeit"/>
<Parameter name="clientAuth" value="true"/>
</Connector>
</pre>
Note that the value used for the <tt>keystore</tt> parameter (shown in
bold above) may be different on your machine; it should contain the full
path and filename of the server keystore file (<tt>server.keystore</tt>)
generated in Step 2a above. Note also that the port number we chose to
use for SSL in the above configuration is 8443. The port normally used
for HTTPS is 443, but for testing we are using 8443.
<h3>
Step 3a: Test your HTTPS server</h3>
At this point, you should restart your Tomcat server. It will probably
take a bit longer to start up. You can now use a web browser to test that
it is working.
<br>Test the SSL installation by opening your browser and typing in the
following URL:
<pre> https://servername:8443/index.html</pre>
Note that <tt>servername</tt> should be replaced with the name of the server
on which you are running Tomcat. If SSL is working then you should see
the default home page for your Tomcat installation.
<br>Your browser may generate a warning about un-trusted certificates or
unrecognised authorities (just click OK).
<h2>
Step 4: Modify the SOAP Client to use SSL</h2>
<h3>
Step 4a: Java SSL Client</h3>
You need to set up properties before you call the URL in the SOAP client.
Here is an example SOAP client that calls a SOAP service using HTTPS on
a Tomcat server:
<pre>
// classes for ssl
import javax.net.ssl.SSLSocketFactory;
import java.security.Security;
...
//
// setup some ssl-specific stuff
//
// specify the location of where to find key material for the default TrustManager (this overrides jssecacerts and cacerts)
<b> System.setProperty("javax.net.ssl.trustStore","C:\\jdk1.3\\bin\\client.keystore");
</b> // use Sun's reference implementation of a URL handler for the "https" URL protocol type.
System.setProperty("java.protocol.handler.pkgs","com.sun.net.ssl.internal.www.protocol");
// dynamically register sun's ssl provider
Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider());
// note that the url is using https protocol and not http
URL urls = new URL( "https://localhost:8443/soap/servlet/rpcrouter");
//
// prepare and then execute a SOAP method
//
// output some basic information
System.out.println("\nUsing " + urls.getProtocol() + " to connect to " + urls.getHost() + " on port #" + urls.getPort());
// prepare the service invocation as usual
Call call = new Call();
String urn = "urn:demo:checkflight";
call.setTargetObjectURI( urn );
call.setMethodName( "getFlightInfo" );
// set up any parameters as usual
...
// Invoke the call
Response resp;
try
{
resp = call.invoke(urls, "");
}
catch (SOAPException e)
{
System.err.println("Caught SOAPException (" + e.getFaultCode() + "): " + e.getMessage());
e.printStackTrace();
return;
}
</pre>
Once again the bold directory path is a pointer to the client keystore.
This may have to be changed depending on where you generated it. Also note
that the url is <b>https</b> and not http. It's an easy mistake to make!
<h3>
Step 4b: Java SSL Client with Proxy [Optional]</h3>
If your client needs to use a proxy server in order to access the SOAP
service, then add the following lines to your code:
<pre>
System.setProperty("https.proxyHost", "proxy"); // set name of proxy server that supports ssl
System.setProperty("https.proxyPort", "8080"); // set port number for proxy server that supports ssl
</pre>
Use the following for Proxy without SSL:
<pre>
System.setProperty("proxySet", "true"); // enable proxying
System.setProperty("proxyHost", "proxy"); // set name of proxy server
System.setProperty("proxyPort", "8080"); // set port number for proxy server
</pre>
If you are using Socks proxy then set these (system) properties:
<pre>
System.setProperty("socksProxyHost", "hostname"); // set name of socks server
System.setProperty("socksProxyPort", "1080"); // set port number for socks server
</pre>
<h2>
Creating X.509 Certificate Chains</h2>
By Darrell Drake
<h3>
Overview</h3>
This instruction set covers creating mutual trust between two entities
using a certificate chains (my certificate with an attached lineage of
public certificates), which is more practical in a production environment
than the minimal security approach. In this case a principal is trusted
if any of the certificates in its chain are trusted. Additional tool needed:
IBM KeyMan, which can read and issue certificates from keystores in the
JKS and PKCS12 formats. Other formats (e.g. IBM CMS Key Database) don't
work well, at least in my experience.
<h3>
Downloading KeyMan</h3>
KeyMan can be downloaded from: <a href="http://www.alphaworks.ibm.com/tech/keyman">http://www.alphaworks.ibm.com/tech/keyman</a>.
<h3>
Creating a new Keystore and Keypair using KeyMan</h3>
<ul>
<li>
From the initial window, click on the "create new" icon on the left</li>
<br>OR
<br>from an already-open KeyMan window, under the File menu choose New.
<li>
Specify the type of keystore (pkcs 7, 12 and JKS are options)</li>
<li>
Immediately the template is created</li>
<li>
Under the Actions menu choose generate key</li>
<li>
Select the desired key algorithm and length, click OK</li>
<li>
WAIT</li>
</ul>
<h3>
Opening an existing keystore file</h3>
<ul>
<li>
From the initial window, click on the "open" icon on the right</li>
<br>OR
<br>from an already-open KeyMan window, under the File menu choose Open
<li>
Select "local resource", click next</li>
<li>
Enter or browse for the filename, click next</li>
<li>
If applicable, enter the password protecting the file</li>
</ul>
<h3>
Generating a self-signed certificate using KeyMan (for new serverkeystore)</h3>
<ul>
<li>
Make sure the new key pair (and just the key pair) is selected</li>
<li>
Under the Actions menu, choose Create Certificate</li>
<li>
Choose Self-Signed Certificate, click next</li>
<li>
Fill in the principal information as requested, click next</li>
<li>
Select the period of validity for the new certificate, click next</li>
</ul>
<h3>
Requesting a client certificate using keytool</h3>
<tt>-- using keytool (after creating keyEntry "alias")</tt>
<br><tt>keytool -certreq {-alias alias} {-sigalg sigalg} {-file certreq_file}
[-keypass keypass] {-storetype storetype} {-keystore keystore} [-storepass
storepass] {-v} {-Jjavaoption}</tt>
<p> If you leave the <tt>"-file certreq_file"</tt> part out, the pkcs10
request will be printed to your standard output, which you can highlight
and copy to the system clipboard, transfer to a file or directly into KeyMan
(see next step "issuing certificate"). The principal information in the
request will be what you entered when using the "-genkey" command earlier.
<h3>
Requesting a client certificate using KeyMan (after creating a key pair)</h3>
<ul>
<li>
Make sure the new key pair (and just the key pair) is selected</li>
<li>
Under the Actions menu, choose Request Certificate</li>
<li>
Choose "Generate a PKCS#10 Request", click next</li>
<br>OR
<br>If you want to get a commercial certificate for your server, choose
"Go online to a CA" (I don't know the remaining steps for doing that)
<li>
Fill in the principal information as requested, click next</li>
<li>
Enter the filename where you want to save the request,</li>
<br>OR
<br>Choose to copy the request to the system clipboard, click next
<li>
The request is now stored in the location that you specified.</li>
</ul>
<h3>
Issuing a client certificate using KeyMan</h3>
(aka acting as your own CA, signing a PKCS#10 certificate request)
<ul>
<li>
Open the keystore that contains your server's private certificate</li>
<li>
Under the Actions menu, choose Create Certificate</li>
<li>
Choose Sign a PKCS#10 request, click next</li>
<li>
Enter or browse for the filename containing the request,</li>
<br>OR
<br>Choose to load the request from the system clipboard (if you stored
it there), click next
<li>
Review the principal info (recommended: verify it offline in production
scenario)</li>
<li>
Select the period of validity for the new certificate, click next</li>
<li>
Enter the [path-qualified] filename where you will store the new certificate,
click next</li>
<li>
NOT RECOMMENDED: saving the certificate to the clipboard (created a single
cert entry on the client side instead of chain in my experience).</li>
</ul>
<h3>
Importing your new certificate from the CA's Using Keytool</h3>
(after importing server's cert as trusted CA cert)
<br><tt>keytool -import {-alias alias} {-file cert_file} [-keypass keypass]
{-storetype storetype} {-keystore keystore} [-storepass storepass] {-v}
{-Jjavaoption}</tt>
<br>It should simply say "certificate was added to keystore" and finish
with no dialog. ["alias" is your original keyEntry; the default self-signed
certificate should now be overwritten with the CA-signed certificate]
<h3>
Importing your new certificate from the CA's Using KeyMan</h3>
<ul>
<li>
Under the File menu, choose Import</li>
<li>
Select "local resource", click next</li>
<li>
Enter or browse for the filename ("cert_file"), click next</li>
<li>
You should get a popup dialog saying "Private Certificate Received", click
OK</li>
</ul>
<h3>
Saving the new or changed keystore file using KeyMan</h3>
<ul>
<li>
Under the File menu choose Save</li>
<li>
Enter the [path-qualified] filename (leave the default file format if PKCS12),
click ok</li>
<li>
Enter the password if prompted</li>
</ul>
NOTE: If the server gets a certificate chain from a higher CA entity, the
client could import that higher entity's certificate as a trusted CA certificate
(it may already have that certificate by default), and it would thus trust
the server certificate.
<h2>
Troubleshooting</h2>
One extremely useful tip for troubleshooting SSL is to use the built-in
SSL debugging features:
<br><tt>java -djavax.net.debug=help YourClassname</tt>
<br>(this will give you a help message for SSL debugging features)
<h3>
Unknown Protocol Error</h3>
Problem: <tt>Exception in thread "main" java.net.MalformedURLException:
unknown protocol: https</tt>
<br>Solution: Ensure that the ssl-specific initialisation code happens
before you create a <tt>java.net.URL</tt> object.
<h3>
Unrecognized SSL handshake</h3>
Problem: <tt>ContextManager: IOException reading request, ignored - javax.net.ssl.SSLException:
Unrecognized SSL handshake.</tt>
<br>Solution: The most likely problem is either:
<br>(a) your url is <tt>http://</tt> instead of <tt>https://</tt>
<br>or
<br>(b) your client and server are using different versions of soap.jar
(possibly 2.0/2.1).
<h3>
Bad Certificate Error</h3>
Redo Steps 2, 3 and 4.
<h3>
Socket Write Error</h3>
Problem: <tt>java.lang.reflect.InvocationTargetException: java.net.SocketException:
Connection aborted by peer: socket write error</tt>
<br>Solution: This problem occurs because (for some reason) the server
cannot authenticate the client. Change the following line in server.xml:
<pre><Parameter name="clientAuth" value="false"/></pre>
<h3>
Keytool Error</h3>
Problem: <tt>keytool error: java.io.IOException: Keystore was tampered
with, or password was incorrect</tt>
<br>Solution: Try deleting the keystore file and re-creating it (see the
instructions at the beginning of this page).
<h2>
Further Information</h2>
<h3>
SOAP</h3>
<ul>
<li>
The SOAP Protocol: <a href="http://www.w3.org/TR/SOAP/">http://www.w3.org/TR/SOAP/</a>.</li>
<li>
Apache SOAP: <a href="http://xml.apache.org/soap/">http://xml.apache.org/soap/</a>.</li>
</ul>
<h3>
SSL</h3>
<ul>
<li>
Sun JSSE FAQ: <a href="http://java.sun.com/products/jsse/FAQ.html">http://java.sun.com/products/jsse/FAQ.html</a></li>
<li>
"Modifying your Java Client to use Secure Sockets Layer": <a href="http://as400bks.rochester.ibm.com/html/as400/v4r5/ic2924/index.htm?info/java/rzaha/sslcex02.htm">http://as400bks.rochester.ibm.com/html/as400/v4r5/ic2924/index.htm?info/java/rzaha/sslcex02.htm</a></li>
<li>
Notes on SSL error codes: <a href="http://www.mozilla.org/projects/security/pki/nss/ref/ssl/sslerr.html">http://www.mozilla.org/projects/security/pki/nss/ref/ssl/sslerr.html</a></li>
<li>
Cryptographic Downloads (includes OpenSSL): <a href="http://www2.psy.uq.edu.au/~ftp/Crypto/">http://www2.psy.uq.edu.au/~ftp/Crypto/</a></li>
</ul>
</body>
</html>
|
