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