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

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

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