| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 1 | <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 (7.0.77) - SSL/TLS 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 |
|
| 8 |
|
| 9 | table {
|
| 10 | border-collapse: collapse;
|
| 11 | text-align: left;
|
| 12 | }
|
| 13 | table *:not(table) {
|
| 14 | /* Prevent border-collapsing for table child elements like <div> */
|
| 15 | border-collapse: separate;
|
| 16 | }
|
| 17 |
|
| 18 | th {
|
| 19 | text-align: left;
|
| 20 | }
|
| 21 |
|
| 22 |
|
| 23 | div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
|
| 24 | background-color: transparent;
|
| 25 | }
|
| 26 | div.codeBox {
|
| 27 | overflow: auto;
|
| 28 | margin: 1em 0;
|
| 29 | }
|
| 30 | div.codeBox pre {
|
| 31 | margin: 0;
|
| 32 | padding: 4px;
|
| 33 | border: 1px solid #999;
|
| 34 | border-radius: 5px;
|
| 35 | background-color: #eff8ff;
|
| 36 | display: table; /* To prevent <pre>s from taking the complete available width. */
|
| 37 | /*
|
| 38 | When it is officially supported, use the following CSS instead of display: table
|
| 39 | to prevent big <pre>s from exceeding the browser window:
|
| 40 | max-width: available;
|
| 41 | width: min-content;
|
| 42 | */
|
| 43 | }
|
| 44 |
|
| 45 | div.codeBox pre.wrap {
|
| 46 | white-space: pre-wrap;
|
| 47 | }
|
| 48 |
|
| 49 |
|
| 50 | table.defaultTable tr, table.detail-table tr {
|
| 51 | border: 1px solid #CCC;
|
| 52 | }
|
| 53 |
|
| 54 | table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
|
| 55 | background-color: #FAFBFF;
|
| 56 | }
|
| 57 |
|
| 58 | table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
|
| 59 | background-color: #EEEFFF;
|
| 60 | }
|
| 61 |
|
| 62 | table.defaultTable th, table.detail-table th {
|
| 63 | background-color: #88b;
|
| 64 | color: #fff;
|
| 65 | }
|
| 66 |
|
| 67 | table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
|
| 68 | padding: 5px 8px;
|
| 69 | }
|
| 70 |
|
| 71 |
|
| 72 | p.notice {
|
| 73 | border: 1px solid rgb(255, 0, 0);
|
| 74 | background-color: rgb(238, 238, 238);
|
| 75 | color: rgb(0, 51, 102);
|
| 76 | padding: 0.5em;
|
| 77 | margin: 1em 2em 1em 1em;
|
| 78 | }
|
| 79 | </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="
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 80 | The Apache Tomcat Servlet/JSP Container
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 81 | " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.77, Mar 28 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></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/TLS</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-descriptors-howto.html">16) MBeans Descriptors</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="websocketapi/index.html">WebSocket 1.1 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/TLS 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>
|
| 82 | <ul><li><a href="#Quick_Start">Quick Start</a></li><li><a href="#Introduction_to_SSL">Introduction to SSL/TLS</a></li><li><a href="#SSL_and_Tomcat">SSL/TLS 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>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 83 | </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>
|
| 84 |
|
| 85 | <blockquote><em>
|
| 86 | <p>The description below uses the variable name $CATALINA_BASE to refer the
|
| 87 | base directory against which most relative paths are resolved. If you have
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 88 | not configured Tomcat for multiple instances by setting a CATALINA_BASE
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 89 | directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 90 | the directory into which you have installed Tomcat.</p>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 91 | </em></blockquote>
|
| 92 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 93 | <p>To install and configure SSL/TLS support on Tomcat, you need to follow
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 94 | these simple steps. For more information, read the rest of this HOW-TO.</p>
|
| 95 | <ol>
|
| 96 | <li>Create a keystore file to store the server's private key and
|
| 97 | self-signed certificate by executing the following command:
|
| 98 | <p>Windows:</p>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 99 | <div class="codeBox"><pre><code>"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA</code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 100 | <p>Unix:</p>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 101 | <div class="codeBox"><pre><code>$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA</code></pre></div>
|
| 102 |
|
| 103 | <p>and specify a password value of "changeit".</p></li>
|
| 104 | <li><p>Uncomment the "SSL HTTP/1.1 Connector" entry in
|
| 105 | <code>$CATALINA_BASE/conf/server.xml</code> and modify as described in
|
| 106 | the <a href="#Configuration">Configuration section</a> below.</p></li>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 107 | </ol>
|
| 108 |
|
| 109 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 110 | </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"><strong>Introduction to SSL/TLS</strong></a></font></td></tr><tr><td><blockquote>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 111 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 112 | <p>Transport Layer Security (TLS) and its predecessor, Secure Sockets Layer
|
| 113 | (SSL), are technologies which allow web browsers and web servers to communicate
|
| 114 | over a secured connection. This means that the data being sent is encrypted by
|
| 115 | one side, transmitted, then decrypted by the other side before processing.
|
| 116 | This is a two-way process, meaning that both the server AND the browser encrypt
|
| 117 | all traffic before sending out data.</p>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 118 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 119 | <p>Another important aspect of the SSL/TLS protocol is Authentication. This means
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 120 | that during your initial attempt to communicate with a web server over a secure
|
| 121 | connection, that server will present your web browser with a set of
|
| 122 | credentials, in the form of a "Certificate", as proof the site is who and what
|
| 123 | it claims to be. In certain cases, the server may also request a Certificate
|
| 124 | from your web browser, asking for proof that <em>you</em> are who you claim
|
| 125 | to be. This is known as "Client Authentication," although in practice this is
|
| 126 | used more for business-to-business (B2B) transactions than with individual
|
| 127 | users. Most SSL-enabled web servers do not request Client Authentication.</p>
|
| 128 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 129 | </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"><strong>SSL/TLS and Tomcat</strong></a></font></td></tr><tr><td><blockquote>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 130 |
|
| 131 | <p>It is important to note that configuring Tomcat to take advantage of
|
| 132 | secure sockets is usually only necessary when running it as a stand-alone
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 133 | web server. Details can be found in the
|
| 134 | <a href="security-howto.html">Security Considerations Document</a>.
|
| 135 | When running Tomcat primarily as a Servlet/JSP container behind
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 136 | another web server, such as Apache or Microsoft IIS, it is usually necessary
|
| 137 | to configure the primary web server to handle the SSL connections from users.
|
| 138 | Typically, this server will negotiate all SSL-related functionality, then
|
| 139 | pass on any requests destined for the Tomcat container only after decrypting
|
| 140 | those requests. Likewise, Tomcat will return cleartext responses, that will
|
| 141 | be encrypted before being returned to the user's browser. In this environment,
|
| 142 | Tomcat knows that communications between the primary web server and the
|
| 143 | client are taking place over a secure connection (because your application
|
| 144 | needs to be able to ask about this), but it does not participate in the
|
| 145 | encryption or decryption itself.</p>
|
| 146 |
|
| 147 | </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>
|
| 148 |
|
| 149 | <p>In order to implement SSL, a web server must have an associated Certificate
|
| 150 | for each external interface (IP address) that accepts secure connections.
|
| 151 | The theory behind this design is that a server should provide some kind of
|
| 152 | reasonable assurance that its owner is who you think it is, particularly
|
| 153 | before receiving any sensitive information. While a broader explanation of
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 154 | Certificates is beyond the scope of this document, think of a Certificate as a
|
| 155 | "digital passport" for an Internet address. It states which organisation the
|
| 156 | site is associated with, along with some basic contact information about the
|
| 157 | site owner or administrator.</p>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 158 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 159 | <p>This certificate is cryptographically signed by its owner, and is
|
| 160 | therefore extremely difficult for anyone else to forge. For the certificate to
|
| 161 | work in the visitors browsers without warnings, it needs to be signed by a
|
| 162 | trusted third party. These are called <em>Certificate Authorities</em> (CAs). To
|
| 163 | obtain a signed certificate, you need to choose a CA and follow the instructions
|
| 164 | your chosen CA provides to obtain your certificate. A range of CAs is available
|
| 165 | including some that offer certificates at no cost.</p>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 166 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 167 | <p>Java provides a relatively simple command-line tool, called
|
| 168 | <code>keytool</code>, which can easily create a "self-signed" Certificate.
|
| 169 | Self-signed Certificates are simply user generated Certificates which have not
|
| 170 | been signed by a well-known CA and are, therefore, not really guaranteed to be
|
| 171 | authentic at all. While self-signed certificates can be useful for some testing
|
| 172 | scenarios, they are not suitable for any form of production use.</p>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 173 |
|
| 174 | </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>
|
| 175 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 176 | <p>When securing a website with SSL it's important to make sure that all assets
|
| 177 | that the site uses are served over SSL, so that an attacker can't bypass
|
| 178 | the security by injecting malicious content in a javascript file or similar. To
|
| 179 | further enhance the security of your website, you should evaluate to use the
|
| 180 | HSTS header. It allows you to communicate to the browser that your site should
|
| 181 | always be accessed over https.</p>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 182 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 183 | <p>Using name-based virtual hosts on a secured connection requires careful
|
| 184 | configuration of the names specified in a single certificate or Tomcat 8.5
|
| 185 | onwards where Server Name Indication (SNI) support is available. SNI allows
|
| 186 | multiple certificates with different names to be associated with a single TLS
|
| 187 | connector.</p>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 188 |
|
| 189 | </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>
|
| 190 |
|
| 191 | <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>
|
| 192 |
|
| 193 | <p>Tomcat currently operates only on <code>JKS</code>, <code>PKCS11</code> or
|
| 194 | <code>PKCS12</code> format keystores. The <code>JKS</code> format
|
| 195 | is Java's standard "Java KeyStore" format, and is the format created by the
|
| 196 | <code>keytool</code> command-line utility. This tool is included in the JDK.
|
| 197 | The <code>PKCS12</code> format is an internet standard, and can be manipulated
|
| 198 | via (among other things) OpenSSL and Microsoft's Key-Manager.
|
| 199 | </p>
|
| 200 |
|
| 201 | <p>Each entry in a keystore is identified by an alias string. Whilst many
|
| 202 | keystore implementations treat aliases in a case insensitive manner, case
|
| 203 | sensitive implementations are available. The <code>PKCS11</code> specification,
|
| 204 | for example, requires that aliases are case sensitive. To avoid issues related
|
| 205 | to the case sensitivity of aliases, it is not recommended to use aliases that
|
| 206 | differ only in case.
|
| 207 | </p>
|
| 208 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 209 | <p>To import an existing certificate into a <code>JKS</code> keystore, please read the
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 210 | documentation (in your JDK documentation package) about <code>keytool</code>.
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 211 | Note that OpenSSL often adds readable comments before the key, but
|
| 212 | <code>keytool</code> does not support that. So if your certificate has
|
| 213 | comments before the key data, remove them before importing the certificate with
|
| 214 | <code>keytool</code>.
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 215 | </p>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 216 | <p>To import an existing certificate signed by your own CA into a <code>PKCS12</code>
|
| 217 | keystore using OpenSSL you would execute a command like:</p>
|
| 218 | <div class="codeBox"><pre><code>openssl pkcs12 -export -in mycert.crt -inkey mykey.key
|
| 219 | -out mycert.p12 -name tomcat -CAfile myCA.crt
|
| 220 | -caname root -chain</code></pre></div>
|
| 221 | <p>For more advanced cases, consult the
|
| 222 | <a href="http://www.openssl.org/" rel="nofollow">OpenSSL documentation</a>.</p>
|
| 223 |
|
| 224 | <p>To create a new <code>JKS</code> keystore from scratch, containing a single
|
| 225 | self-signed Certificate, execute the following from a terminal command line:</p>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 226 | <p>Windows:</p>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 227 | <div class="codeBox"><pre><code>"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA</code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 228 | <p>Unix:</p>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 229 | <div class="codeBox"><pre><code>$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA</code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 230 |
|
| 231 | <p>(The RSA algorithm should be preferred as a secure algorithm, and this
|
| 232 | also ensures general compatibility with other servers and components.)</p>
|
| 233 |
|
| 234 | <p>This command will create a new file, in the home directory of the user
|
| 235 | under which you run it, named "<code>.keystore</code>". To specify a
|
| 236 | different location or filename, add the <code>-keystore</code> parameter,
|
| 237 | followed by the complete pathname to your keystore file,
|
| 238 | to the <code>keytool</code> command shown above. You will also need to
|
| 239 | reflect this new location in the <code>server.xml</code> configuration file,
|
| 240 | as described later. For example:</p>
|
| 241 | <p>Windows:</p>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 242 | <div class="codeBox"><pre><code>"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA
|
| 243 | -keystore \path\to\my\keystore</code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 244 | <p>Unix:</p>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 245 | <div class="codeBox"><pre><code>$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
|
| 246 | -keystore /path/to/my/keystore</code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 247 |
|
| 248 | <p>After executing this command, you will first be prompted for the keystore
|
| 249 | password. The default password used by Tomcat is "<code>changeit</code>"
|
| 250 | (all lower case), although you can specify a custom password if you like.
|
| 251 | You will also need to specify the custom password in the
|
| 252 | <code>server.xml</code> configuration file, as described later.</p>
|
| 253 |
|
| 254 | <p>Next, you will be prompted for general information about this Certificate,
|
| 255 | such as company, contact name, and so on. This information will be displayed
|
| 256 | to users who attempt to access a secure page in your application, so make
|
| 257 | sure that the information provided here matches what they will expect.</p>
|
| 258 |
|
| 259 | <p>Finally, you will be prompted for the <em>key password</em>, which is the
|
| 260 | password specifically for this Certificate (as opposed to any other
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 261 | Certificates stored in the same keystore file). The <code>keytool</code> prompt
|
| 262 | will tell you that pressing the ENTER key automatically uses the same password
|
| 263 | for the key as the keystore. You are free to use the same password or to select
|
| 264 | a custom one. If you select a different password to the keystore password, you
|
| 265 | will also need to specify the custom password in the <code>server.xml</code>
|
| 266 | configuration file.</p>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 267 |
|
| 268 | <p>If everything was successful, you now have a keystore file with a
|
| 269 | Certificate that can be used by your server.</p>
|
| 270 |
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 271 | </blockquote></td></tr></table>
|
| 272 |
|
| 273 | <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>
|
| 274 | <p>
|
| 275 | Tomcat can use two different implementations of SSL:
|
| 276 | <ul>
|
| 277 | <li>the JSSE implementation provided as part of the Java runtime (since 1.4)</li>
|
| 278 | <li>the APR implementation, which uses the OpenSSL engine by default.</li>
|
| 279 | </ul>
|
| 280 | The exact configuration details depend on which implementation is being used.
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 281 | If you configured Connector by specifying generic
|
| 282 | <code>protocol="HTTP/1.1"</code> then the implementation used by Tomcat is
|
| 283 | chosen automatically. If the installation uses <a href="apr.html">APR</a>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 284 | - i.e. you have installed the Tomcat native library -
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 285 | then it will use the APR SSL implementation, otherwise it will use the Java
|
| 286 | JSSE implementation.
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 287 | </p>
|
| 288 |
|
| 289 | <p>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 290 | As configuration attributes for SSL support significantly differ between
|
| 291 | APR vs. JSSE implementations, it is <strong>recommended</strong> to
|
| 292 | avoid auto-selection of implementation. It is done by specifying a classname
|
| 293 | in the <b>protocol</b> attribute of the <a href="config/http.html">Connector</a>.</p>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 294 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 295 | <p>To define a Java (JSSE) connector, regardless of whether the APR library is
|
| 296 | loaded or not, use one of the following:</p>
|
| 297 | <div class="codeBox"><pre><code><!-- Define a HTTP/1.1 Connector on port 8443, JSSE NIO implementation -->
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 298 | <Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
|
| 299 | port="8443" .../>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 300 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 301 | <!-- Define a HTTP/1.1 Connector on port 8443, JSSE BIO implementation -->
|
| 302 | <Connector protocol="org.apache.coyote.http11.Http11Protocol"
|
| 303 | port="8443" .../></code></pre></div>
|
| 304 | <p>Alternatively, to specify an APR connector (the APR library must be available) use:</p>
|
| 305 | <div class="codeBox"><pre><code><!-- Define a HTTP/1.1 Connector on port 8443, APR implementation -->
|
| 306 | <Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
|
| 307 | port="8443" .../></code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 308 |
|
| 309 | <p>If you are using APR, you have the option of configuring an alternative engine to OpenSSL.
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 310 | <div class="codeBox"><pre><code>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 311 | <Listener className="org.apache.catalina.core.AprLifecycleListener"
|
| 312 | SSLEngine="someengine" SSLRandomSeed="somedevice" />
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 313 | </code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 314 | The default value is
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 315 | <div class="codeBox"><pre><code>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 316 | <Listener className="org.apache.catalina.core.AprLifecycleListener"
|
| 317 | SSLEngine="on" SSLRandomSeed="builtin" />
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 318 | </code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 319 | So to use SSL under APR, make sure the SSLEngine attribute is set to something other than <code>off</code>.
|
| 320 | The default value is <code>on</code> and if you specify another value, it has to be a valid engine name.
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 321 | </p>
|
| 322 |
|
| 323 | <p>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 324 | SSLRandomSeed allows to specify a source of entropy. Productive system needs a reliable source of entropy
|
| 325 | but entropy may need a lot of time to be collected therefore test systems could use no blocking entropy
|
| 326 | sources like "/dev/urandom" that will allow quicker starts of Tomcat.
|
| 327 |
|
| 328 | </p>
|
| 329 |
|
| 330 | <p>The final step is to configure the Connector in the
|
| 331 | <code>$CATALINA_BASE/conf/server.xml</code> file, where
|
| 332 | <code>$CATALINA_BASE</code> represents the base directory for the
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 333 | Tomcat instance. An example <code><Connector></code> element
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 334 | for an SSL connector is included in the default <code>server.xml</code>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 335 | file installed with Tomcat. To configure an SSL connector that uses JSSE, you
|
| 336 | will need to remove the comments and edit it so it looks something like
|
| 337 | this:</p>
|
| 338 | <div class="codeBox"><pre><code>
|
| 339 | <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
|
| 340 | <Connector
|
| 341 | protocol="org.apache.coyote.http11.Http11NioProtocol"
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 342 | port="8443" maxThreads="200"
|
| 343 | scheme="https" secure="true" SSLEnabled="true"
|
| 344 | keystoreFile="${user.home}/.keystore" keystorePass="changeit"
|
| 345 | clientAuth="false" sslProtocol="TLS"/>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 346 | </code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 347 | <p>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 348 | The APR connector uses different attributes for many SSL settings,
|
| 349 | particularly keys and certificates. An example of an APR configuration is:
|
| 350 | <div class="codeBox"><pre><code>
|
| 351 | <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
|
| 352 | <Connector
|
| 353 | protocol="org.apache.coyote.http11.Http11AprProtocol"
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 354 | port="8443" maxThreads="200"
|
| 355 | scheme="https" secure="true" SSLEnabled="true"
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 356 | SSLCertificateFile="/usr/local/ssl/server.crt"
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 357 | SSLCertificateKeyFile="/usr/local/ssl/server.pem"
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 358 | SSLVerifyClient="optional" SSLProtocol="TLSv1+TLSv1.1+TLSv1.2"/>
|
| 359 | </code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 360 | </p>
|
| 361 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 362 | <p>The configuration options and information on which attributes
|
| 363 | are mandatory, are documented in the SSL Support section of the
|
| 364 | <a href="config/http.html#SSL Support">HTTP connector</a> configuration
|
| 365 | reference. Make sure that you use the correct attributes for the connector you
|
| 366 | are using. The BIO and NIO connectors use JSSE whereas the APR/native connector
|
| 367 | uses APR.</p>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 368 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 369 | <p>The <code>port</code> attribute is the TCP/IP
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 370 | port number on which Tomcat will listen for secure connections. You can
|
| 371 | change this to any port number you wish (such as to the default port for
|
| 372 | <code>https</code> communications, which is 443). However, special setup
|
| 373 | (outside the scope of this document) is necessary to run Tomcat on port
|
| 374 | numbers lower than 1024 on many operating systems.</p>
|
| 375 |
|
| 376 | <blockquote><em>
|
| 377 | <p>If you change the port number here, you should also change the
|
| 378 | value specified for the <code>redirectPort</code> attribute on the
|
| 379 | non-SSL connector. This allows Tomcat to automatically redirect
|
| 380 | users who attempt to access a page with a security constraint specifying
|
| 381 | that SSL is required, as required by the Servlet Specification.</p>
|
| 382 | </em></blockquote>
|
| 383 |
|
| 384 | <p>After completing these configuration changes, you must restart Tomcat as
|
| 385 | you normally do, and you should be in business. You should be able to access
|
| 386 | any web application supported by Tomcat via SSL. For example, try:</p>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 387 | <div class="codeBox"><pre><code>https://localhost:8443/</code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 388 | <p>and you should see the usual Tomcat splash page (unless you have modified
|
| 389 | the ROOT web application). If this does not work, the following section
|
| 390 | contains some troubleshooting tips.</p>
|
| 391 |
|
| 392 | </blockquote></td></tr></table>
|
| 393 |
|
| 394 | </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>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 395 | <p>To obtain and install a Certificate from a Certificate Authority (like verisign.com, thawte.com
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 396 | or trustcenter.de), read the previous section and then follow these instructions:</p>
|
| 397 |
|
| 398 | <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>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 399 | <p>In order to obtain a Certificate from the Certificate Authority of your choice
|
| 400 | you have to create a so called Certificate Signing Request (CSR). That CSR will be used
|
| 401 | by the Certificate Authority to create a Certificate that will identify your website
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 402 | as "secure". To create a CSR follow these steps:</p>
|
| 403 | <ul>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 404 | <li>Create a local self-signed Certificate (as described in the previous section):
|
| 405 | <div class="codeBox"><pre><code>keytool -genkey -alias tomcat -keyalg RSA
|
| 406 | -keystore <your_keystore_filename></code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 407 | Note: In some cases you will have to enter the domain of your website (i.e. <code>www.myside.org</code>)
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 408 | in the field "first- and lastname" in order to create a working Certificate.
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 409 | </li>
|
| 410 | <li>The CSR is then created with:
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 411 | <div class="codeBox"><pre><code>keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr
|
| 412 | -keystore <your_keystore_filename></code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 413 | </li>
|
| 414 | </ul>
|
| 415 | <p>Now you have a file called <code>certreq.csr</code> that you can submit to the Certificate Authority (look at the
|
| 416 | documentation of the Certificate Authority website on how to do this). In return you get a Certificate.</p>
|
| 417 | </blockquote></td></tr></table>
|
| 418 |
|
| 419 | <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>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 420 | <p>Now that you have your Certificate you can import it into you local keystore.
|
| 421 | First of all you have to import a so called Chain Certificate or Root Certificate into your keystore.
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 422 | After that you can proceed with importing your Certificate.</p>
|
| 423 |
|
| 424 | <ul>
|
| 425 | <li>Download a Chain Certificate from the Certificate Authority you obtained the Certificate from.<br>
|
| 426 | For Verisign.com commercial certificates go to:
|
| 427 | http://www.verisign.com/support/install/intermediate.html<br>
|
| 428 | For Verisign.com trial certificates go to:
|
| 429 | http://www.verisign.com/support/verisign-intermediate-ca/Trial_Secure_Server_Root/index.html<br>
|
| 430 | For Trustcenter.de go to:
|
| 431 | http://www.trustcenter.de/certservices/cacerts/en/en.htm#server<br>
|
| 432 | For Thawte.com go to:
|
| 433 | http://www.thawte.com/certs/trustmap.html<br>
|
| 434 | </li>
|
| 435 | <li>Import the Chain Certificate into your keystore
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 436 | <div class="codeBox"><pre><code>keytool -import -alias root -keystore <your_keystore_filename>
|
| 437 | -trustcacerts -file <filename_of_the_chain_certificate></code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 438 | </li>
|
| 439 | <li>And finally import your new Certificate
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 440 | <div class="codeBox"><pre><code>keytool -import -alias tomcat -keystore <your_keystore_filename>
|
| 441 | -file <your_certificate_filename></code></pre></div>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 442 | </li>
|
| 443 | </ul>
|
| 444 | </blockquote></td></tr></table>
|
| 445 | </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>
|
| 446 |
|
| 447 | <p>Here is a list of common problems that you may encounter when setting up
|
| 448 | SSL communications, and what to do about them.</p>
|
| 449 |
|
| 450 | <ul>
|
| 451 |
|
| 452 | <li>When Tomcat starts up, I get an exception like
|
| 453 | "java.io.FileNotFoundException: {some-directory}/{some-file} not found".
|
| 454 | <blockquote>
|
| 455 | <p>A likely explanation is that Tomcat cannot find the keystore file
|
| 456 | where it is looking. By default, Tomcat expects the keystore file to
|
| 457 | be named <code>.keystore</code> in the user home directory under which
|
| 458 | Tomcat is running (which may or may not be the same as yours :-). If
|
| 459 | the keystore file is anywhere else, you will need to add a
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 460 | <code>keystoreFile</code> attribute to the <code><Connector></code>
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 461 | element in the <a href="#Edit the Tomcat Configuration File">Tomcat
|
| 462 | configuration file</a>.</p>
|
| 463 | </blockquote></li>
|
| 464 |
|
| 465 | <li>When Tomcat starts up, I get an exception like
|
| 466 | "java.io.FileNotFoundException: Keystore was tampered with, or
|
| 467 | password was incorrect".
|
| 468 | <blockquote>
|
| 469 | <p>Assuming that someone has not <em>actually</em> tampered with
|
| 470 | your keystore file, the most likely cause is that Tomcat is using
|
| 471 | a different password than the one you used when you created the
|
| 472 | keystore file. To fix this, you can either go back and
|
| 473 | <a href="#Prepare the Certificate Keystore">recreate the keystore
|
| 474 | file</a>, or you can add or update the <code>keystorePass</code>
|
| 475 | attribute on the <code><Connector></code> element in the
|
| 476 | <a href="#Edit the Tomcat Configuration File">Tomcat configuration
|
| 477 | file</a>. <strong>REMINDER</strong> - Passwords are case sensitive!</p>
|
| 478 | </blockquote></li>
|
| 479 |
|
| 480 | <li>When Tomcat starts up, I get an exception like
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 481 | "java.net.SocketException: SSL handshake error javax.net.ssl.SSLException: No
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 482 | available certificate or key corresponds to the SSL cipher suites which are
|
| 483 | enabled."
|
| 484 | <blockquote>
|
| 485 | <p>A likely explanation is that Tomcat cannot find the alias for the server
|
| 486 | key within the specified keystore. Check that the correct
|
| 487 | <code>keystoreFile</code> and <code>keyAlias</code> are specified in the
|
| 488 | <code><Connector></code> element in the
|
| 489 | <a href="#Edit the Tomcat Configuration File">Tomcat configuration file</a>.
|
| 490 | <strong>REMINDER</strong> - <code>keyAlias</code> values may be case
|
| 491 | sensitive!</p>
|
| 492 | </blockquote></li>
|
| 493 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 494 | <li>My Java-based client aborts handshakes with exceptions such as
|
| 495 | "java.lang.RuntimeException: Could not generate DH keypair" and
|
| 496 | "java.security.InvalidAlgorithmParameterException: Prime size must be multiple
|
| 497 | of 64, and can only range from 512 to 1024 (inclusive)"
|
| 498 |
|
| 499 | <p>If you are using the APR/native connector, starting with version 1.1.34
|
| 500 | it will determine the strength of ephemeral DH keys from the key size of
|
| 501 | your RSA certificate. For example a 2048 bit RSA key will result in
|
| 502 | using a 2048 bit primefor the DH keys. Unfortunately Java 6 only supports
|
| 503 | 768 bit and Java 7 only supports 1024 bit. So if your certificate has a
|
| 504 | stronger key, old Java clients might produce such handshake failures.
|
| 505 | As a mitigation you can either try to force them to use another cipher by
|
| 506 | configuring an appropriate <code>SSLCipherSuite</code> and activate
|
| 507 | <code>SSLHonorCipherOrder</code>, or embed weak DH params in your
|
| 508 | certificate file. The latter approach is not recommended because it weakens
|
| 509 | the SSL security (logjam attack).</p>
|
| 510 | </li>
|
| 511 |
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 512 | </ul>
|
| 513 |
|
| 514 | <p>If you are still having problems, a good source of information is the
|
| 515 | <strong>TOMCAT-USER</strong> mailing list. You can find pointers to archives
|
| 516 | of previous messages on this list, as well as subscription and unsubscription
|
| 517 | information, at
|
| 518 | <a href="http://tomcat.apache.org/lists.html">http://tomcat.apache.org/lists.html</a>.</p>
|
| 519 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 520 | </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>
|
| 521 | <p>This is a new feature in the Servlet 3.0 specification. Because it uses the
|
| 522 | SSL session ID associated with the physical client-server connection there
|
| 523 | are some limitations. They are:
|
| 524 | <ul>
|
| 525 | <li>Tomcat must have a connector with the attribute
|
| 526 | <strong>isSecure</strong> set to <code>true</code>.</li>
|
| 527 | <li>If SSL connections are managed by a proxy or a hardware accelerator
|
| 528 | they must populate the SSL request headers (see the
|
| 529 | <a href="config/valve.html">SSLValve</a>) so that
|
| 530 | the SSL session ID is visible to Tomcat.</li>
|
| 531 | <li>If Tomcat terminates the SSL connection, it will not be possible to use
|
| 532 | session replication as the SSL session IDs will be different on each
|
| 533 | node.</li>
|
| 534 | </ul>
|
| 535 | </p>
|
| 536 |
|
| 537 | <p>
|
| 538 | To enable SSL session tracking you need to use a context listener to set the
|
| 539 | tracking mode for the context to be just SSL (if any other tracking mode is
|
| 540 | enabled, it will be used in preference). It might look something like:
|
| 541 | <div class="codeBox"><pre><code>
|
| 542 | package org.apache.tomcat.example;
|
| 543 |
|
| 544 | import java.util.EnumSet;
|
| 545 |
|
| 546 | import javax.servlet.ServletContext;
|
| 547 | import javax.servlet.ServletContextEvent;
|
| 548 | import javax.servlet.ServletContextListener;
|
| 549 | import javax.servlet.SessionTrackingMode;
|
| 550 |
|
| 551 | public class SessionTrackingModeListener implements ServletContextListener {
|
| 552 |
|
| 553 | @Override
|
| 554 | public void contextDestroyed(ServletContextEvent event) {
|
| 555 | // Do nothing
|
| 556 | }
|
| 557 |
|
| 558 | @Override
|
| 559 | public void contextInitialized(ServletContextEvent event) {
|
| 560 | ServletContext context = event.getServletContext();
|
| 561 | EnumSet<SessionTrackingMode> modes =
|
| 562 | EnumSet.of(SessionTrackingMode.SSL);
|
| 563 |
|
| 564 | context.setSessionTrackingModes(modes);
|
| 565 | }
|
| 566 |
|
| 567 | }
|
| 568 | </code></pre></div>
|
| 569 | </p>
|
| 570 | <p>Note: SSL session tracking is implemented for the BIO and NIO connectors.
|
| 571 | It is not yet implemented for the APR connector.</p>
|
| 572 |
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 573 | </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>
|
| 574 |
|
| 575 | <p>To access the SSL session ID from the request, use:<br>
|
| 576 |
|
| 577 | <code>
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 578 | String sslID = (String)request.getAttribute("javax.servlet.request.ssl_session_id");
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 579 | </code>
|
| 580 | <br>
|
| 581 | For additional discussion on this area, please see
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 582 | <a href="http://bz.apache.org/bugzilla/show_bug.cgi?id=22679">Bugzilla</a>.
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 583 | </p>
|
| 584 |
|
| 刘洪青 | 6266f99 | 2017-05-15 21:21:03 +0800 | [diff] [blame^] | 585 | <p>To terminate an SSL session, use:
|
| 586 | <div class="codeBox"><pre><code>
|
| 587 | // Standard HTTP session invalidation
|
| 588 | session.invalidate();
|
| 589 |
|
| 590 | // Invalidate the SSL Session
|
| 591 | org.apache.tomcat.util.net.SSLSessionManager mgr =
|
| 592 | (org.apache.tomcat.util.net.SSLSessionManager)
|
| 593 | request.getAttribute("javax.servlet.request.ssl_session_mgr");
|
| 594 | mgr.invalidateSession();
|
| 595 |
|
| 596 | // Close the connection since the SSL session will be active until the connection
|
| 597 | // is closed
|
| 598 | response.setHeader("Connection", "close");
|
| 599 | </code></pre></div>
|
| 600 | Note that this code is Tomcat specific due to the use of the
|
| 601 | SSLSessionManager class. This is currently only available for the BIO and
|
| 602 | NIO connectors, not the APR/native connector.
|
| 603 | </p>
|
| 604 | </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
|
| 605 | on improving documentation for Apache Tomcat.<br><br>
|
| 606 | If you have trouble and need help, read
|
| 607 | <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
|
| 608 | and ask your question on the tomcat-users
|
| 609 | <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
|
| 610 | Do not ask such questions here. This is not a Q&A section.<br><br>
|
| 611 | The Apache Comments System is explained <a href="./comments.html">here</a>.
|
| 612 | Comments may be removed by our moderators if they are either
|
| 613 | implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
|
| 614 | var comments_shortname = 'tomcat';
|
| 615 | var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html';
|
| 616 | (function(w, d) {
|
| 617 | if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
|
| 618 | d.write('<div id="comments_thread"><\/div>');
|
| 619 | var s = d.createElement('script');
|
| 620 | s.type = 'text/javascript';
|
| 621 | s.async = true;
|
| 622 | s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
|
| 623 | (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
|
| 624 | }
|
| 625 | else {
|
| 626 | d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
|
| 627 | }
|
| 628 | })(window, document);
|
| 629 | //--><!]]></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>
|
| 630 | Copyright © 1999-2017, Apache Software Foundation
|
| Hongqing Liu | fd5ee81 | 2014-05-10 16:32:51 +0800 | [diff] [blame] | 631 | </em></font></div></td></tr></table></body></html> |