source: nutchez-0.1/tomcat/webapps/docs/printer/ssl-howto.html @ 222

Last change on this file since 222 was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 54.6 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - SSL Configuration HOW-TO</title><meta value="Christopher Cain" name="author"><meta value="ccain@apache.org" name="email"><meta value="Yoav Shapira" name="author"><meta value="yoavs@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
2      The Apache Tomcat Servlet/JSP Container
3    " align="right" src="./../images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="./../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Apache Tomcat 6.0</h1><h2>SSL Configuration HOW-TO</h2></td><td nowrap="true" valign="top" align="right"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Quick Start"><strong>Quick Start</strong></a></font></td></tr><tr><td><blockquote>
4
5   <p><b>IMPORTANT NOTE: This Howto refers to usage of JSSE, that comes included with
6    jdk 1.5 and higher. When using APR, Tomcat will
7    use OpenSSL, which uses a different configuration.</b></p>
8
9    <blockquote><em>
10    <p>The description below uses the variable name $CATALINA_BASE to refer the
11    base directory against which most relative paths are resolved. If you have
12    not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE
13    directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
14    the directory into which you have installed Tomcat 6.</p>
15    </em></blockquote>
16
17<p>To install and configure SSL support on Tomcat 6, you need to follow
18these simple steps.  For more information, read the rest of this HOW-TO.</p>
19<ol>
20<li>Create a certificate keystore by executing the following command:
21<p>Windows:</p>
22<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
23%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
24</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
25<p>Unix:</p>
26<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
27$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
28</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
29<p></p>
30    and specify a password value of "changeit".</li><br><br>
31<li>Uncomment the "SSL HTTP/1.1 Connector" entry in
32    <code>$CATALINA_BASE/conf/server.xml</code> and tweak as necessary.</li>
33    <br><br>
34</ol>
35
36
37</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction to SSL"><strong>Introduction to SSL</strong></a></font></td></tr><tr><td><blockquote>
38
39<p>SSL, or Secure Socket Layer, is a technology which allows web browsers and
40web servers to communicate over a secured connection.  This means that the data
41being sent is encrypted by one side, transmitted, then decrypted by the other
42side before processing.  This is a two-way process, meaning that both the
43server AND the browser encrypt all traffic before sending out data.</p>
44
45<p>Another important aspect of the SSL protocol is Authentication.  This means
46that during your initial attempt to communicate with a web server over a secure
47connection, that server will present your web browser with a set of
48credentials, in the form of a "Certificate", as proof the site is who and what
49it claims to be.  In certain cases, the server may also request a Certificate
50from your web browser, asking for proof that <em>you</em> are who you claim
51to be.  This is known as "Client Authentication," although in practice this is
52used more for business-to-business (B2B) transactions than with individual
53users.  Most SSL-enabled web servers do not request Client Authentication.</p>
54
55</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="SSL and Tomcat"><strong>SSL and Tomcat</strong></a></font></td></tr><tr><td><blockquote>
56
57<p>It is important to note that configuring Tomcat to take advantage of
58secure sockets is usually only necessary when running it as a stand-alone
59web server.  When running Tomcat primarily as a Servlet/JSP container behind
60another web server, such as Apache or Microsoft IIS, it is usually necessary
61to configure the primary web server to handle the SSL connections from users.
62Typically, this server will negotiate all SSL-related functionality, then
63pass on any requests destined for the Tomcat container only after decrypting
64those requests.  Likewise, Tomcat will return cleartext responses, that will
65be encrypted before being returned to the user's browser.  In this environment,
66Tomcat knows that communications between the primary web server and the
67client are taking place over a secure connection (because your application
68needs to be able to ask about this), but it does not participate in the
69encryption or decryption itself.</p>
70
71</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Certificates"><strong>Certificates</strong></a></font></td></tr><tr><td><blockquote>
72
73<p>In order to implement SSL, a web server must have an associated Certificate
74for each external interface (IP address) that accepts secure connections.
75The theory behind this design is that a server should provide some kind of
76reasonable assurance that its owner is who you think it is, particularly
77before receiving any sensitive information.  While a broader explanation of
78Certificates is beyond the scope of this document, think of a Certificate
79as a "digital driver's license" for an Internet address.  It states what
80company the site is associated with, along with some basic contact
81information about the site owner or administrator.</p>
82
83<p>This "driver's license" is cryptographically signed by its owner, and is
84therefore extremely difficult for anyone else to forge.  For sites involved
85in e-commerce, or any other business transaction in which authentication of
86identity is important, a Certificate is typically purchased from a well-known
87<em>Certificate Authority</em> (CA) such as VeriSign or Thawte.  Such
88certificates can be electronically verified -- in effect, the Certificate
89Authority will vouch for the authenticity of the certificates that it grants,
90so you can believe that that Certificate is valid if you trust the Certificate
91Authority that granted it.</p>
92
93<p>In many cases, however, authentication is not really a concern.  An
94administrator may simply want to ensure that the data being transmitted and
95received by the server is private and cannot be snooped by anyone who may be
96eavesdropping on the connection.  Fortunately, Java provides a relatively
97simple command-line tool, called <code>keytool</code>, which can easily create
98a "self-signed" Certificate.  Self-signed Certificates are simply user
99generated Certificates which have not been officially registered with any
100well-known CA, and are therefore not really guaranteed to be authentic at all.
101Again, this may or may not even be important, depending on your needs.</p>
102
103</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="General Tips on Running SSL"><strong>General Tips on Running SSL</strong></a></font></td></tr><tr><td><blockquote>
104
105<p>The first time a user attempts to access a secured page on your site,
106he or she is typically presented with a dialog containing the details of
107the certificate (such as the company and contact name), and asked if he or she
108wishes to accept the Certificate as valid and continue with the transaction.
109Some browsers will provide an option for permanently accepting a given
110Certificate as valid, in which case the user will not be bothered with a
111prompt each time they visit your site.  Other browsers do not provide this
112option.  Once approved by the user, a Certificate will be considered valid
113for at least the entire browser session.</p>
114
115<p>Also, while the SSL protocol was designed to be as efficient as securely
116possible, encryption/decryption is a computationally expensive process from
117a performance standpoint.  It is not strictly necessary to run an entire
118web application over SSL, and indeed a developer can pick and choose which
119pages require a secure connection and which do not.  For a reasonably busy
120site, it is customary to only run certain pages under SSL, namely those
121pages where sensitive information could possibly be exchanged.  This would
122include things like login pages, personal information pages, and shopping
123cart checkouts, where credit card information could possibly be transmitted.
124Any page within an application can be requested over a secure socket by
125simply prefixing the address with <code>https:</code> instead of
126<code>http:</code>.  Any pages which absolutely <strong>require</strong>
127a secure connection should check the protocol type associated with the
128page request and take the appropriate action if <code>https</code> is not
129specified.</p>
130
131<p>Finally, using name-based virtual hosts on a secured connection can be
132problematic.  This is a design limitation of the SSL protocol itself.  The SSL
133handshake, where the client browser accepts the server certificate, must occur
134before the HTTP request is accessed.  As a result, the request information
135containing the virtual host name cannot be determined prior to authentication,
136and it is therefore not possible to assign multiple certificates to a single
137IP address.  If all virtual hosts on a single IP address need to authenticate
138against the same certificate, the addition of multiple virtual hosts should not
139interfere with normal SSL operations on the server.  Be aware, however, that
140most client browsers will compare the server's domain name against the domain
141name listed in the certificate, if any (applicable primarily to official,
142CA-signed certificates).  If the domain names do not match, these browsers will
143display a warning to the client user.  In general, only address-based virtual
144hosts are commonly used with SSL in a production environment.</p>
145
146</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Configuration"><strong>Configuration</strong></a></font></td></tr><tr><td><blockquote>
147
148<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Prepare the Certificate Keystore"><strong>Prepare the Certificate Keystore</strong></a></font></td></tr><tr><td><blockquote>
149
150<p>Tomcat currently operates only on <code>JKS</code>, <code>PKCS11</code> or
151<code>PKCS12</code> format keystores.  The <code>JKS</code> format
152is Java's standard "Java KeyStore" format, and is the format created by the
153<code>keytool</code> command-line utility.  This tool is included in the JDK.
154The <code>PKCS12</code> format is an internet standard, and can be manipulated
155via (among other things) OpenSSL and Microsoft's Key-Manager.
156</p>
157
158<p>Each entry in a keystore is identified by an alias string. Whilst many
159keystore implementations treat aliases in a case insensitive manner, case
160sensitive implementations are available. The <code>PKCS11</code> specification,
161for example, requires that aliases are case sensitive. To avoid issues related
162to the case sensitivity of aliases, it is not recommended to use aliases that
163differ only in case.
164</p>
165
166<p>To import an existing certificate into a JKS keystore, please read the
167documentation (in your JDK documentation package) about <code>keytool</code>.
168Note that OpenSSL often adds readable comments before the key,
169<code>keytool</code>does not support that, so remove the OpenSSL comments if
170they exist before importing the key using <code>keytool</code>.
171</p>
172<p>To import an existing certificate signed by your own CA into a PKCS12
173keystore using OpenSSL you would execute a command like:
174<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>openssl pkcs12 -export -in mycert.crt -inkey mykey.key \
175                        -out mycert.p12 -name tomcat -CAfile myCA.crt \
176                        -caname root -chain
177</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
178For more advanced cases, consult the <a href="http://www.openssl.org/">OpenSSL
179documentation</a>.
180</p>
181<p>To create a new keystore from scratch, containing a single self-signed
182Certificate, execute the following from a terminal command line:</p>
183<p>Windows:</p>
184<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
185%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
186</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
187<p>Unix:</p>
188<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
189$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
190</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
191
192<p>(The RSA algorithm should be preferred as a secure algorithm, and this
193also ensures general compatibility with other servers and components.)</p>
194
195<p>This command will create a new file, in the home directory of the user
196under which you run it, named "<code>.keystore</code>".  To specify a
197different location or filename, add the <code>-keystore</code> parameter,
198followed by the complete pathname to your keystore file,
199to the <code>keytool</code> command shown above.  You will also need to
200reflect this new location in the <code>server.xml</code> configuration file,
201as described later.  For example:</p>
202<p>Windows:</p>
203<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
204%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
205  -keystore \path\to\my\keystore
206</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
207<p>Unix:</p>
208<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
209$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
210  -keystore /path/to/my/keystore
211</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
212
213<p>After executing this command, you will first be prompted for the keystore
214password.  The default password used by Tomcat is "<code>changeit</code>"
215(all lower case), although you can specify a custom password if you like.
216You will also need to specify the custom password in the
217<code>server.xml</code> configuration file, as described later.</p>
218
219<p>Next, you will be prompted for general information about this Certificate,
220such as company, contact name, and so on.  This information will be displayed
221to users who attempt to access a secure page in your application, so make
222sure that the information provided here matches what they will expect.</p>
223
224<p>Finally, you will be prompted for the <em>key password</em>, which is the
225password specifically for this Certificate (as opposed to any other
226Certificates stored in the same keystore file).  You <strong>MUST</strong>
227use the same password here as was used for the keystore password itself.
228(Currently, the <code>keytool</code> prompt will tell you that pressing the
229ENTER key does this for you automatically.)</p>
230
231<p>If everything was successful, you now have a keystore file with a
232Certificate that can be used by your server.</p>
233
234<p><strong>Note:</strong> your private key password and keystore password
235should be the same.  If they differ, you will get an error along the lines
236of <code>java.io.IOException: Cannot recover key</code>, as documented in
237<a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=38217">Bugzilla issue 38217</a>,
238which contains further references for this issue.</p>
239
240</blockquote></td></tr></table>
241
242<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Edit the Tomcat Configuration File"><strong>Edit the Tomcat Configuration File</strong></a></font></td></tr><tr><td><blockquote>
243<p>If you are using APR, you have the option of configuring an alternative engine to OpenSSL.
244<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
245&lt;Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="someengine" SSLRandomSeed="somedevice" /&gt;
246</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
247The default value is
248<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
249&lt;Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" SSLRandomSeed="builtin" /&gt;
250</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
251So to use SSL under APR, make sure the SSLEngine attribute is set to something other than <code>off</code>.
252The default value is <code>on</code> and if you specify another value, it has to be a valid engine name.
253<br>
254If you haven't compiled in SSL support into your Tomcat Native library, then you can turn this initialization off
255<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
256&lt;Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="off" /&gt;
257</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
258SSLRandomSeed allows to specify a source of entropy. Productive system needs a reliable source of entropy
259but entropy may need a lot of time to be collected therefore test systems could use no blocking entropy
260sources like "/dev/urandom" that will allow quicker starts of Tomcat.
261
262</p>
263
264<p>The final step is to configure your secure socket in the
265<code>$CATALINA_BASE/conf/server.xml</code> file, where
266<code>$CATALINA_BASE</code> represents the base directory for the
267Tomcat 6 instance.  An example <code>&lt;Connector&gt;</code> element
268for an SSL connector is included in the default <code>server.xml</code>
269file installed with Tomcat.  It will look something like this:</p>
270<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
271&lt;-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
272&lt;!--
273&lt;Connector
274           port="8443" minSpareThreads="5" maxSpareThreads="75"
275           enableLookups="true" disableUploadTimeout="true"
276           acceptCount="100"  maxThreads="200"
277           scheme="https" secure="true" SSLEnabled="true"
278           keystoreFile="${user.home}/.keystore" keystorePass="changeit"
279           clientAuth="false" sslProtocol="TLS"/&gt;
280--&gt;
281</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
282<p>
283  The example above will throw an error if you have the APR and the Tomcat Native libraries in your path,
284  as tomcat will try to autoload the APR connector. The APR connector uses different attributes for
285  SSL keys and certificates. An example of such configuration would be
286<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
287&lt;-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
288&lt;!--
289&lt;Connector
290           port="8443" minSpareThreads="5" maxSpareThreads="75"
291           enableLookups="true" disableUploadTimeout="true"
292           acceptCount="100"  maxThreads="200"
293           scheme="https" secure="true" SSLEnabled="true"
294           SSLCertificateFile="/usr/local/ssl/server.crt"
295           SSLCertificateKeyFile="/usr/local/ssl/server.pem"
296           clientAuth="false" sslProtocol="TLS"/&gt;
297--&gt;
298</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
299</p>
300
301<p>
302  To avoid auto configuration you can define which connector to use by specifying a classname
303  in the protocol attribute.<br>
304  To define a Java connector, regardless if the APR library is loaded or not do:
305<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
306&lt;-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
307&lt;!--
308&lt;Connector protocol="org.apache.coyote.http11.Http11Protocol"
309           port="8443" minSpareThreads="5" maxSpareThreads="75"
310           enableLookups="true" disableUploadTimeout="true"
311           acceptCount="100"  maxThreads="200"
312           scheme="https" secure="true" SSLEnabled="true"
313           keystoreFile="${user.home}/.keystore" keystorePass="changeit"
314           clientAuth="false" sslProtocol="TLS"/&gt;
315--&gt;
316&lt;-- Define a non-blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
317&lt;!--
318&lt;Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
319           port="8443" minSpareThreads="5" maxSpareThreads="75"
320           enableLookups="true" disableUploadTimeout="true"
321           acceptCount="100"  maxThreads="200"
322           scheme="https" secure="true" SSLEnabled="true"
323           keystoreFile="${user.home}/.keystore" keystorePass="changeit"
324           clientAuth="false" sslProtocol="TLS"/&gt;
325--&gt;
326</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
327and to specify an APR connector
328<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
329&lt;-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
330&lt;!--
331&lt;Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
332           port="8443" minSpareThreads="5" maxSpareThreads="75"
333           enableLookups="true" disableUploadTimeout="true"
334           acceptCount="100"  maxThreads="200"
335           scheme="https" secure="true" SSLEnabled="true"
336           SSLCertificateFile="/usr/local/ssl/server.crt"
337           SSLCertificateKeyFile="/usr/local/ssl/server.pem"
338           clientAuth="false" sslProtocol="TLS"/&gt;
339--&gt;
340</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
341
342</p>
343
344<p>You will note that the Connector element itself is commented out by default,
345so you will need to remove the comment tags around it.  Then, you can
346customize the specified attributes as necessary.  For detailed information
347about the various options, consult the
348<a href="../config/index.html">Server Configuration Reference</a>.  The
349following discussion covers only those attributes of most interest when
350setting up SSL communication.</p>
351
352<p>The <code>port</code> attribute (default value is 8443) is the TCP/IP
353port number on which Tomcat will listen for secure connections.  You can
354change this to any port number you wish (such as to the default port for
355<code>https</code> communications, which is 443).  However, special setup
356(outside the scope of this document) is necessary to run Tomcat on port
357numbers lower than 1024 on many operating systems.</p>
358
359  <blockquote><em>
360  <p>If you change the port number here, you should also change the
361  value specified for the <code>redirectPort</code> attribute on the
362  non-SSL connector.  This allows Tomcat to automatically redirect
363  users who attempt to access a page with a security constraint specifying
364  that SSL is required, as required by the Servlet 2.4 Specification.</p>
365  </em></blockquote>
366
367<p>There are additional options used to configure the SSL protocol.
368  You may need to add or change the following attribute
369values, depending on how you configured your keystore earlier:</p>
370
371<table border="1">
372  <tr>
373    <th>Attribute</th>
374    <th>Description</th>
375  </tr>
376  <tr>
377    <td><code>clientAuth</code></td>
378    <td>Set this value to <code>true</code> if you want Tomcat to require
379        all SSL clients to present a client Certificate in order to use
380        this socket.  Set this value to <code>want</code> if you want Tomcat
381        to request a client Certificate, but not fail if one isn't presented.
382    </td>
383  </tr>
384  <tr><td><code>SSLEnabled</code></td>
385    <td>
386      Use this attribute to enable SSL traffic on a connector.
387      To turn on SSL handshake/encryption/decryption on a connector
388      set this value to <code>true</code>.
389      The default value is <code>false</code>.
390      When turning this value <code>true</code> you will want to set the
391      <code>scheme</code> and the <code>secure</code> attributes as well
392      to pass the correct <code>request.getScheme()</code> and
393      <code>request.isSecure()</code> values to the servlets
394    </td>
395  </tr> 
396  <tr>
397    <td><code>keystoreFile</code></td>
398    <td>Add this attribute if the keystore file you created is not in
399        the default place that Tomcat expects (a file named
400        <code>.keystore</code> in the user home directory under
401        which Tomcat is running).  You can specify an absolute pathname,
402        or a relative pathname that is resolved against the
403        <code>$CATALINA_BASE</code> environment variable.</td>
404  </tr>
405  <tr>
406    <td><code>keystorePass</code></td>
407    <td>Add this element if you used a different keystore (and Certificate)
408        password than the one Tomcat expects (<code>changeit</code>).</td>
409  </tr>
410  <tr>
411    <td><code>keystoreType</code></td>
412    <td>Add this element if using a keystore type other than <code>JKS</code>.
413    For example the *.p12 files from OpenSSL can be used using <code>PKCS12</code>.</td>
414  </tr>
415  <tr>
416    <td><code>sslProtocol</code></td>
417    <td>The encryption/decryption protocol to be used on this socket.
418        It is not recommended to change this value if you are using Sun's
419        JVM.  It is reported that IBM's 1.4.1 implementation
420        of the TLS protocol is not compatible with some popular browsers.
421        In this case, use the value <code>SSL</code>.</td>
422  </tr>
423  <tr>
424    <td><code>ciphers</code></td>
425    <td>The comma separated list of encryption ciphers that this socket is
426        allowed to use.  By default, any available cipher is allowed.</td>
427  </tr>
428  <tr>
429    <td><code>algorithm</code></td>
430    <td>The <code>X509</code> algorithm to use.  This defaults to the Sun
431        implementation (<code>SunX509</code>).  For IBM JVMs you should use
432        the value <code>IbmX509</code>.  For other vendors, consult the JVM
433        documentation for the correct value.
434    </td>
435  </tr>
436  <tr>
437   <td><code>truststoreFile</code></td>
438   <td>The TrustStore file to use to validate client certificates.</td>
439  </tr>
440  <tr>
441   <td><code>truststorePass</code></td>
442   <td>The password to access the TrustStore.  This defaults to the value
443       of <code>keystorePass</code>.</td>
444  </tr>
445  <tr>
446   <td><code>truststoreType</code></td>
447    <td>Add this element if your are using a different format for the
448        TrustStore then you are using for the KeyStore.</td>
449  </tr>
450  <tr>
451   <td><code>keyAlias</code></td>
452    <td>Add this element if your have more than one key in the KeyStore.
453        If the element is not present the first key read in the KeyStore
454        will be used.</td>
455  </tr>
456</table>
457
458<p>After completing these configuration changes, you must restart Tomcat as
459you normally do, and you should be in business.  You should be able to access
460any web application supported by Tomcat via SSL.  For example, try:</p>
461<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
462https://localhost:8443
463</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
464
465<p>and you should see the usual Tomcat splash page (unless you have modified
466the ROOT web application).  If this does not work, the following section
467contains some troubleshooting tips.</p>
468
469</blockquote></td></tr></table>
470
471</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Installing a Certificate from a Certificate Authority"><strong>Installing a Certificate from a Certificate Authority</strong></a></font></td></tr><tr><td><blockquote>
472<p>To obtain and install a Certificate from a Certificate Authority (like verisign.com, thawte.com
473or trustcenter.de), read the previous section and then follow these instructions:</p>
474
475<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Create a local Certificate Signing Request (CSR)"><strong>Create a local Certificate Signing Request (CSR)</strong></a></font></td></tr><tr><td><blockquote>
476<p>In order to obtain a Certificate from the Certificate Authority of your choice
477you have to create a so called Certificate Signing Request (CSR). That CSR will be used
478by the Certificate Authority to create a Certificate that will identify your website
479as "secure". To create a CSR follow these steps:</p>
480<ul>
481<li>Create a local Certificate (as described in the previous section):
482  <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>keytool -genkey -alias tomcat -keyalg RSA \
483  -keystore &lt;your_keystore_filename&gt;</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
484  Note: In some cases you will have to enter the domain of your website (i.e. <code>www.myside.org</code>)
485  in the field "first- and lastname" in order to create a working Certificate.
486</li>
487<li>The CSR is then created with:
488  <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr \
489  -keystore &lt;your_keystore_filename&gt;</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
490</li>
491</ul>
492<p>Now you have a file called <code>certreq.csr</code> that you can submit to the Certificate Authority (look at the
493documentation of the Certificate Authority website on how to do this). In return you get a Certificate.</p>
494</blockquote></td></tr></table>
495
496<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Importing the Certificate"><strong>Importing the Certificate</strong></a></font></td></tr><tr><td><blockquote>
497<p>Now that you have your Certificate you can import it into you local keystore.
498First of all you have to import a so called Chain Certificate or Root Certificate into your keystore.
499After that you can proceed with importing your Certificate.</p>
500
501<ul>
502<li>Download a Chain Certificate from the Certificate Authority you obtained the Certificate from.<br>
503  For Verisign.com commercial certificates go to:
504            http://www.verisign.com/support/install/intermediate.html<br>
505        For Verisign.com trial certificates go to:
506            http://www.verisign.com/support/verisign-intermediate-ca/Trial_Secure_Server_Root/index.html<br>
507  For Trustcenter.de go to:
508            http://www.trustcenter.de/certservices/cacerts/en/en.htm#server<br>
509  For Thawte.com go to:
510            http://www.thawte.com/certs/trustmap.html<br>
511</li>
512<li>Import the Chain Certificate into your keystore
513    <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>keytool -import -alias root -keystore &lt;your_keystore_filename&gt; \
514  -trustcacerts -file &lt;filename_of_the_chain_certificate&gt;</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
515</li>
516<li>And finally import your new Certificate
517  <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>keytool -import -alias tomcat -keystore &lt;your_keystore_filename&gt; \
518  -file &lt;your_certificate_filename&gt;</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./../images/void.gif"></td></tr></table></div>
519</li>
520</ul>
521</blockquote></td></tr></table>
522</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Troubleshooting"><strong>Troubleshooting</strong></a></font></td></tr><tr><td><blockquote>
523
524<p>Here is a list of common problems that you may encounter when setting up
525SSL communications, and what to do about them.</p>
526
527<ul>
528
529<li>I get "java.security.NoSuchAlgorithmException" errors in my
530    log files.
531    <blockquote>
532    <p>The JVM cannot find the JSSE JAR files.  Follow all of the directions to
533    <a href="#Download and Install JSSE">download and install JSSE</a>.</p>
534    </blockquote></li>
535
536<li>When Tomcat starts up, I get an exception like
537    "java.io.FileNotFoundException: {some-directory}/{some-file} not found".
538    <blockquote>
539    <p>A likely explanation is that Tomcat cannot find the keystore file
540    where it is looking.  By default, Tomcat expects the keystore file to
541    be named <code>.keystore</code> in the user home directory under which
542    Tomcat is running (which may or may not be the same as yours :-).  If
543    the keystore file is anywhere else, you will need to add a
544    <code>keystoreFile</code> attribute to the <code>&lt;Factory&gt;</code>
545    element in the <a href="#Edit the Tomcat Configuration File">Tomcat
546    configuration file</a>.</p>
547    </blockquote></li>
548
549<li>When Tomcat starts up, I get an exception like
550    "java.io.FileNotFoundException:  Keystore was tampered with, or
551    password was incorrect".
552    <blockquote>
553    <p>Assuming that someone has not <em>actually</em> tampered with
554    your keystore file, the most likely cause is that Tomcat is using
555    a different password than the one you used when you created the
556    keystore file.  To fix this, you can either go back and
557    <a href="#Prepare the Certificate Keystore">recreate the keystore
558    file</a>, or you can add or update the <code>keystorePass</code>
559    attribute on the <code>&lt;Connector&gt;</code> element in the
560    <a href="#Edit the Tomcat Configuration File">Tomcat configuration
561    file</a>.  <strong>REMINDER</strong> - Passwords are case sensitive!</p>
562    </blockquote></li>
563
564<li>When Tomcat starts up, I get an exception like
565    "java.net.SocketException: SSL handshake errorjavax.net.ssl.SSLException: No
566    available certificate or key corresponds to the SSL cipher suites which are
567    enabled."
568    <blockquote>
569    <p>A likely explanation is that Tomcat cannot find the alias for the server
570    key withinthe specified keystore. Check that the correct
571    <code>keystoreFile</code> and <code>keyAlias</code> are specified in the
572    <code>&lt;Connector&gt;</code> element in the
573    <a href="#Edit the Tomcat Configuration File">Tomcat configuration file</a>.
574    <strong>REMINDER</strong> - <code>keyAlias</code> values may be case
575    sensitive!</p>
576    </blockquote></li>
577
578</ul>
579
580<p>If you are still having problems, a good source of information is the
581<strong>TOMCAT-USER</strong> mailing list.  You can find pointers to archives
582of previous messages on this list, as well as subscription and unsubscription
583information, at
584<a href="http://tomcat.apache.org/lists.html">http://tomcat.apache.org/lists.html</a>.</p>
585
586</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Miscellaneous Tips and Bits"><strong>Miscellaneous Tips and Bits</strong></a></font></td></tr><tr><td><blockquote>
587
588<p>To access the SSL session ID from the request, use:<br>
589
590  <code>
591    String sslID = (String)request.getAttribute("javax.servlet.request.ssl_session");
592  </code>
593<br>
594For additional discussion on this area, please see
595<a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=22679">Bugzilla</a>.
596</p>
597</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
598        Copyright &copy; 1999-2008, Apache Software Foundation
599        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.