Details | Last modification | View Log | RSS feed
| Rev | Author | Line No. | Line |
|---|---|---|---|
| 771 | blopes | 1 | <!DOCTYPE html SYSTEM "about:legacy-compat"> |
| 2 | <html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="./images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 (9.0.112) - SSL/TLS Configuration How-To</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="./images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="./images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9</h1><div class="versionInfo"> |
||
| 3 | Version 9.0.112, |
||
| 4 | <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="index.html">Docs Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li></ul></div><div><h2>User Guide</h2><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="host-manager-howto.html">6) Host Manager</a></li><li><a href="realm-howto.html">7) Realms and AAA</a></li><li><a href="security-manager-howto.html">8) Security Manager</a></li><li><a href="jndi-resources-howto.html">9) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">10) JDBC DataSources</a></li><li><a href="class-loader-howto.html">11) Classloading</a></li><li><a href="jasper-howto.html">12) JSPs</a></li><li><a href="ssl-howto.html">13) SSL/TLS</a></li><li><a href="ssi-howto.html">14) SSI</a></li><li><a href="cgi-howto.html">15) CGI</a></li><li><a href="proxy-howto.html">16) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">17) MBeans Descriptors</a></li><li><a href="default-servlet.html">18) Default Servlet</a></li><li><a href="cluster-howto.html">19) Clustering</a></li><li><a href="balancer-howto.html">20) Load Balancer</a></li><li><a href="connectors.html">21) Connectors</a></li><li><a href="monitoring.html">22) Monitoring and Management</a></li><li><a href="logging.html">23) Logging</a></li><li><a href="apr.html">24) APR/Native</a></li><li><a href="virtual-hosting-howto.html">25) Virtual Hosting</a></li><li><a href="aio.html">26) Advanced IO</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><li><a href="rewrite.html">33) Rewrite</a></li><li><a href="cdi.html">34) CDI 2 and JAX-RS</a></li><li><a href="graal.html">35) AOT/GraalVM Support</a></li></ul></div><div><h2>Reference</h2><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 4.0 Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.3 Javadocs</a></li><li><a href="elapi/index.html">EL 3.0 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="jaspicapi/index.html">JASPIC 1.1 Javadocs</a></li><li><a href="annotationapi/index.html">Common Annotations 1.3 Javadocs</a></li><li><a href="https://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul></div><div><h2>Apache Tomcat Development</h2><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/Tomcat+Versions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>SSL/TLS Configuration How-To</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text"> |
||
| 5 | <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="#Using_OCSP_Certificates">Using OCSP Certificates</a><ol><li><a href="#Generating_OCSP-Enabled_Certificates">Generating OCSP-Enabled Certificates</a></li><li><a href="#Configuring_OCSP_Connector">Configuring OCSP Connector</a></li><li><a href="#Starting_OCSP_Responder">Starting OCSP Responder</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> |
||
| 6 | </div><h3 id="Quick_Start">Quick Start</h3><div class="text"> |
||
| 7 | |||
| 8 | <p><em>The description below uses the variable name $CATALINA_BASE to refer the |
||
| 9 | base directory against which most relative paths are resolved. If you have |
||
| 10 | not configured Tomcat for multiple instances by setting a CATALINA_BASE |
||
| 11 | directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, |
||
| 12 | the directory into which you have installed Tomcat.</em></p> |
||
| 13 | |||
| 14 | <p>To install and configure SSL/TLS support on Tomcat, you need to follow |
||
| 15 | these simple steps. For more information, read the rest of this How-To.</p> |
||
| 16 | <ol> |
||
| 17 | <li><p>Create a keystore file to store the server's private key and |
||
| 18 | self-signed certificate by executing the following command:</p> |
||
| 19 | <p>Windows:</p> |
||
| 20 | <div class="codeBox"><pre><code>"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA</code></pre></div> |
||
| 21 | <p>Unix:</p> |
||
| 22 | <div class="codeBox"><pre><code>$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA</code></pre></div> |
||
| 23 | |||
| 24 | <p>and specify a password value of "changeit".</p></li> |
||
| 25 | <li><p>Uncomment the "SSL HTTP/1.1 Connector" entry in |
||
| 26 | <code>$CATALINA_BASE/conf/server.xml</code> and modify as described in |
||
| 27 | the <a href="#Configuration">Configuration section</a> below.</p></li> |
||
| 28 | |||
| 29 | </ol> |
||
| 30 | |||
| 31 | |||
| 32 | </div><h3 id="Introduction_to_SSL">Introduction to SSL/TLS</h3><div class="text"> |
||
| 33 | |||
| 34 | <p>Transport Layer Security (TLS) and its predecessor, Secure Sockets Layer |
||
| 35 | (SSL), are technologies which allow web browsers and web servers to communicate |
||
| 36 | over a secured connection. This means that the data being sent is encrypted by |
||
| 37 | one side, transmitted, then decrypted by the other side before processing. |
||
| 38 | This is a two-way process, meaning that both the server AND the browser encrypt |
||
| 39 | all traffic before sending out data.</p> |
||
| 40 | |||
| 41 | <p>Another important aspect of the SSL/TLS protocol is Authentication. This means |
||
| 42 | that during your initial attempt to communicate with a web server over a secure |
||
| 43 | connection, that server will present your web browser with a set of |
||
| 44 | credentials, in the form of a "Certificate", as proof the site is who and what |
||
| 45 | it claims to be. In certain cases, the server may also request a Certificate |
||
| 46 | from your web browser, asking for proof that <em>you</em> are who you claim |
||
| 47 | to be. This is known as "Client Authentication," although in practice this is |
||
| 48 | used more for business-to-business (B2B) transactions than with individual |
||
| 49 | users. Most SSL-enabled web servers do not request Client Authentication.</p> |
||
| 50 | |||
| 51 | </div><h3 id="SSL_and_Tomcat">SSL/TLS and Tomcat</h3><div class="text"> |
||
| 52 | |||
| 53 | <p>It is important to note that configuring Tomcat to take advantage of |
||
| 54 | secure sockets is usually only necessary when running it as a stand-alone |
||
| 55 | web server. Details can be found in the |
||
| 56 | <a href="security-howto.html">Security Considerations Document</a>. |
||
| 57 | When running Tomcat primarily as a Servlet/JSP container behind |
||
| 58 | another web server, such as Apache or Microsoft IIS, it is usually necessary |
||
| 59 | to configure the primary web server to handle the SSL connections from users. |
||
| 60 | Typically, this server will negotiate all SSL-related functionality, then |
||
| 61 | pass on any requests destined for the Tomcat container only after decrypting |
||
| 62 | those requests. Likewise, Tomcat will return cleartext responses, that will |
||
| 63 | be encrypted before being returned to the user's browser. In this environment, |
||
| 64 | Tomcat knows that communications between the primary web server and the |
||
| 65 | client are taking place over a secure connection (because your application |
||
| 66 | needs to be able to ask about this), but it does not participate in the |
||
| 67 | encryption or decryption itself.</p> |
||
| 68 | |||
| 69 | <p>Tomcat is able to use any of the cryptographic protocols that are |
||
| 70 | provided by the underlying environment. Java itself provides cryptographic |
||
| 71 | capabilities through <a href="https://docs.oracle.com/javase/9/security/java-cryptography-architecture-jca-reference-guide.htm">JCE/JCA</a> |
||
| 72 | and encrypted communications capabilities through <a href="https://docs.oracle.com/javase/9/security/java-secure-socket-extension-jsse-reference-guide.htm">JSSE</a>. |
||
| 73 | Any compliant cryptographic "provider" can provide cryptographic algorithms |
||
| 74 | to Tomcat. The built-in provider (SunJCE) includes support for various |
||
| 75 | SSL/TLS versions like SSLv3, TLSv1, TLSv1.1, and so on. Check the documentation |
||
| 76 | for your version of Java for details on protocol and algorithm support.</p> |
||
| 77 | |||
| 78 | <p>If you use the optional <code>tcnative</code> library, you can use |
||
| 79 | the <a href="https://www.openssl.org/">OpenSSL</a> cryptographic provider |
||
| 80 | through JCA/JCE/JSSE which may provide a different selection of cryptographic |
||
| 81 | algorithms and/or performance benefits relative to the SunJCE provider. |
||
| 82 | You can also use <code>tcnative</code> to enable the <a href="apr.html">APR</a> |
||
| 83 | connector which uses OpenSSL for its cryptographic operations. Check the |
||
| 84 | documentation for your version of OpenSSL for details on protocol and |
||
| 85 | algorithm support.</p> |
||
| 86 | |||
| 87 | </div><h3 id="Certificates">Certificates</h3><div class="text"> |
||
| 88 | |||
| 89 | <p>In order to implement SSL, a web server must have an associated Certificate |
||
| 90 | for each external interface (IP address) that accepts secure connections. |
||
| 91 | The theory behind this design is that a server should provide some kind of |
||
| 92 | reasonable assurance that its owner is who you think it is, particularly |
||
| 93 | before receiving any sensitive information. While a broader explanation of |
||
| 94 | Certificates is beyond the scope of this document, think of a Certificate as a |
||
| 95 | "digital passport" for an Internet address. It states which organisation the |
||
| 96 | site is associated with, along with some basic contact information about the |
||
| 97 | site owner or administrator.</p> |
||
| 98 | |||
| 99 | <p>This certificate is cryptographically signed by its owner, and is |
||
| 100 | therefore extremely difficult for anyone else to forge. For the certificate to |
||
| 101 | work in the visitors browsers without warnings, it needs to be signed by a |
||
| 102 | trusted third party. These are called <em>Certificate Authorities</em> (CAs). To |
||
| 103 | obtain a signed certificate, you need to choose a CA and follow the instructions |
||
| 104 | your chosen CA provides to obtain your certificate. A range of CAs is available |
||
| 105 | including some that offer certificates at no cost.</p> |
||
| 106 | |||
| 107 | <p>Java provides a relatively simple command-line tool, called |
||
| 108 | <code>keytool</code>, which can easily create a "self-signed" Certificate. |
||
| 109 | Self-signed Certificates are simply user generated Certificates which have not |
||
| 110 | been signed by a well-known CA and are, therefore, not really guaranteed to be |
||
| 111 | authentic at all. While self-signed certificates can be useful for some testing |
||
| 112 | scenarios, they are not suitable for any form of production use.</p> |
||
| 113 | |||
| 114 | </div><h3 id="General_Tips_on_Running_SSL">General Tips on Running SSL</h3><div class="text"> |
||
| 115 | |||
| 116 | <p>When securing a website with SSL it's important to make sure that all assets |
||
| 117 | that the site uses are served over SSL, so that an attacker can't bypass |
||
| 118 | the security by injecting malicious content in a JavaScript file or similar. To |
||
| 119 | further enhance the security of your website, you should evaluate to use the |
||
| 120 | HSTS header. It allows you to communicate to the browser that your site should |
||
| 121 | always be accessed over https.</p> |
||
| 122 | |||
| 123 | <p>Using name-based virtual hosts on a secured connection requires careful |
||
| 124 | configuration of the names specified in a single certificate or Tomcat 8.5 |
||
| 125 | onwards where Server Name Indication (SNI) support is available. SNI allows |
||
| 126 | multiple certificates with different names to be associated with a single TLS |
||
| 127 | connector.</p> |
||
| 128 | |||
| 129 | </div><h3 id="Configuration">Configuration</h3><div class="text"> |
||
| 130 | |||
| 131 | <div class="subsection"><h4 id="Prepare_the_Certificate_Keystore">Prepare the Certificate Keystore</h4><div class="text"> |
||
| 132 | |||
| 133 | <p>Tomcat currently operates only on <code>JKS</code>, <code>PKCS11</code> or |
||
| 134 | <code>PKCS12</code> format keystores. The <code>JKS</code> format |
||
| 135 | is Java's standard "Java KeyStore" format, and is the format created by the |
||
| 136 | <code>keytool</code> command-line utility. This tool is included in the JDK. |
||
| 137 | The <code>PKCS12</code> format is an internet standard, and can be manipulated |
||
| 138 | via (among other things) OpenSSL and Microsoft's Key-Manager. |
||
| 139 | </p> |
||
| 140 | |||
| 141 | <p>Each entry in a keystore is identified by an alias string. Whilst many |
||
| 142 | keystore implementations treat aliases in a case insensitive manner, case |
||
| 143 | sensitive implementations are available. The <code>PKCS11</code> specification, |
||
| 144 | for example, requires that aliases are case sensitive. To avoid issues related |
||
| 145 | to the case sensitivity of aliases, it is not recommended to use aliases that |
||
| 146 | differ only in case. |
||
| 147 | </p> |
||
| 148 | |||
| 149 | <p>To import an existing certificate into a <code>JKS</code> keystore, please read the |
||
| 150 | documentation (in your JDK documentation package) about <code>keytool</code>. |
||
| 151 | Note that OpenSSL often adds readable comments before the key, but |
||
| 152 | <code>keytool</code> does not support that. So if your certificate has |
||
| 153 | comments before the key data, remove them before importing the certificate with |
||
| 154 | <code>keytool</code>. |
||
| 155 | </p> |
||
| 156 | <p>To import an existing certificate signed by your own CA into a <code>PKCS12</code> |
||
| 157 | keystore using OpenSSL you would execute a command like:</p> |
||
| 158 | <div class="codeBox"><pre><code>openssl pkcs12 -export -in mycert.crt -inkey mykey.key |
||
| 159 | -out mycert.p12 -name tomcat -CAfile myCA.crt |
||
| 160 | -caname root -chain</code></pre></div> |
||
| 161 | <p>For more advanced cases, consult the |
||
| 162 | <a href="https://www.openssl.org/" rel="nofollow">OpenSSL documentation</a>.</p> |
||
| 163 | |||
| 164 | <p>To create a new <code>JKS</code> keystore from scratch, containing a single |
||
| 165 | self-signed Certificate, execute the following from a terminal command line:</p> |
||
| 166 | <p>Windows:</p> |
||
| 167 | <div class="codeBox"><pre><code>"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA</code></pre></div> |
||
| 168 | <p>Unix:</p> |
||
| 169 | <div class="codeBox"><pre><code>$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA</code></pre></div> |
||
| 170 | |||
| 171 | <p>(The RSA algorithm should be preferred as a secure algorithm, and this |
||
| 172 | also ensures general compatibility with other servers and components.)</p> |
||
| 173 | |||
| 174 | <p>This command will create a new file, in the home directory of the user |
||
| 175 | under which you run it, named "<code>.keystore</code>". To specify a |
||
| 176 | different location or filename, add the <code>-keystore</code> parameter, |
||
| 177 | followed by the complete pathname to your keystore file, |
||
| 178 | to the <code>keytool</code> command shown above. You will also need to |
||
| 179 | reflect this new location in the <code>server.xml</code> configuration file, |
||
| 180 | as described later. For example:</p> |
||
| 181 | <p>Windows:</p> |
||
| 182 | <div class="codeBox"><pre><code>"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA |
||
| 183 | -keystore \path\to\my\keystore</code></pre></div> |
||
| 184 | <p>Unix:</p> |
||
| 185 | <div class="codeBox"><pre><code>$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA |
||
| 186 | -keystore /path/to/my/keystore</code></pre></div> |
||
| 187 | |||
| 188 | <p>After executing this command, you will first be prompted for the keystore |
||
| 189 | password. The default password used by Tomcat is "<code>changeit</code>" |
||
| 190 | (all lower case), although you can specify a custom password if you like. |
||
| 191 | You will also need to specify the custom password in the |
||
| 192 | <code>server.xml</code> configuration file, as described later.</p> |
||
| 193 | |||
| 194 | <p>Next, you will be prompted for general information about this Certificate, |
||
| 195 | such as company, contact name, and so on. This information will be displayed |
||
| 196 | to users who attempt to access a secure page in your application, so make |
||
| 197 | sure that the information provided here matches what they will expect.</p> |
||
| 198 | |||
| 199 | <p>Finally, you will be prompted for the <em>key password</em>, which is the |
||
| 200 | password specifically for this Certificate (as opposed to any other |
||
| 201 | Certificates stored in the same keystore file). The <code>keytool</code> prompt |
||
| 202 | will tell you that pressing the ENTER key automatically uses the same password |
||
| 203 | for the key as the keystore. You are free to use the same password or to select |
||
| 204 | a custom one. If you select a different password to the keystore password, you |
||
| 205 | will also need to specify the custom password in the <code>server.xml</code> |
||
| 206 | configuration file.</p> |
||
| 207 | |||
| 208 | <p>If everything was successful, you now have a keystore file with a |
||
| 209 | Certificate that can be used by your server.</p> |
||
| 210 | |||
| 211 | </div></div> |
||
| 212 | |||
| 213 | <div class="subsection"><h4 id="Edit_the_Tomcat_Configuration_File">Edit the Tomcat Configuration File</h4><div class="text"> |
||
| 214 | <p> |
||
| 215 | Tomcat can use three different implementations of SSL: |
||
| 216 | </p> |
||
| 217 | <ul> |
||
| 218 | <li>JSSE implementation provided as part of the Java runtime</li> |
||
| 219 | <li>JSSE implementation that uses OpenSSL</li> |
||
| 220 | <li>APR implementation, which uses the OpenSSL engine by default</li> |
||
| 221 | </ul> |
||
| 222 | <p> |
||
| 223 | The exact configuration details depend on which implementation is being used. |
||
| 224 | If you configured Connector by specifying generic |
||
| 225 | <code>protocol="HTTP/1.1"</code> then the implementation used by Tomcat is |
||
| 226 | chosen automatically. If the installation uses <a href="apr.html">APR</a> |
||
| 227 | - i.e. you have installed the Tomcat native library - |
||
| 228 | then it will use the JSSE OpenSSL implementation, otherwise it will use the Java |
||
| 229 | JSSE implementation. |
||
| 230 | </p> |
||
| 231 | |||
| 232 | <p> |
||
| 233 | Auto-selection of implementation can be avoided if needed. It is done by specifying a classname |
||
| 234 | in the <b>protocol</b> attribute of the <a href="config/http.html">Connector</a>.</p> |
||
| 235 | |||
| 236 | <p>To define a Java (JSSE) connector, regardless of whether the APR library is |
||
| 237 | loaded or not, use one of the following:</p> |
||
| 238 | <div class="codeBox"><pre><code><!-- Define an HTTP/1.1 Connector on port 8443, JSSE NIO implementation --> |
||
| 239 | <Connector protocol="org.apache.coyote.http11.Http11NioProtocol" |
||
| 240 | sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation" |
||
| 241 | port="8443" .../> |
||
| 242 | |||
| 243 | <!-- Define an HTTP/1.1 Connector on port 8443, JSSE NIO2 implementation --> |
||
| 244 | <Connector protocol="org.apache.coyote.http11.Http11Nio2Protocol" |
||
| 245 | sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation" |
||
| 246 | port="8443" .../></code></pre></div> |
||
| 247 | |||
| 248 | <p>The OpenSSL JSSE implementation can also be configured explicitly if needed. If the APR library |
||
| 249 | is installed (as for using the APR connector), using the sslImplementationName attribute |
||
| 250 | allows enabling it. When using the OpenSSL JSSE implementation, the configuration can use |
||
| 251 | either the JSSE attributes or |
||
| 252 | the OpenSSL attributes (as used for the APR connector), but must not mix attributes from |
||
| 253 | both types in the same SSLHostConfig or Connector element.</p> |
||
| 254 | <div class="codeBox"><pre><code><!-- Define an HTTP/1.1 Connector on port 8443, JSSE NIO implementation and OpenSSL --> |
||
| 255 | <Connector protocol="org.apache.coyote.http11.Http11NioProtocol" port="8443" |
||
| 256 | sslImplementationName="org.apache.tomcat.util.net.openssl.OpenSSLImplementation" |
||
| 257 | .../></code></pre></div> |
||
| 258 | |||
| 259 | <p>Alternatively, to specify an APR connector (the APR library must be available) use:</p> |
||
| 260 | <div class="codeBox"><pre><code><!-- Define an HTTP/1.1 Connector on port 8443, APR implementation --> |
||
| 261 | <Connector protocol="org.apache.coyote.http11.Http11AprProtocol" |
||
| 262 | port="8443" .../></code></pre></div> |
||
| 263 | |||
| 264 | <p>If you are using APR or JSSE OpenSSL, you have the option of configuring an alternative engine to OpenSSL.</p> |
||
| 265 | <div class="codeBox"><pre><code><Listener className="org.apache.catalina.core.AprLifecycleListener" |
||
| 266 | SSLEngine="someengine" SSLRandomSeed="somedevice" /></code></pre></div> |
||
| 267 | <p>The default value is</p> |
||
| 268 | <div class="codeBox"><pre><code><Listener className="org.apache.catalina.core.AprLifecycleListener" |
||
| 269 | SSLEngine="on" SSLRandomSeed="builtin" /></code></pre></div> |
||
| 270 | <p>Also the <code>useAprConnector</code> attribute may be used to have Tomcat default to |
||
| 271 | using the APR connector rather than the NIO connector:</p> |
||
| 272 | <div class="codeBox"><pre><code><Listener className="org.apache.catalina.core.AprLifecycleListener" |
||
| 273 | useAprConnector="true" SSLEngine="on" SSLRandomSeed="builtin" /></code></pre></div> |
||
| 274 | <p> |
||
| 275 | So to enable OpenSSL, make sure the SSLEngine attribute is set to something other than <code>off</code>. |
||
| 276 | The default value is <code>on</code> and if you specify another value, |
||
| 277 | it has to be a valid OpenSSL engine name. |
||
| 278 | </p> |
||
| 279 | |||
| 280 | <p> |
||
| 281 | SSLRandomSeed allows to specify a source of entropy. Productive system needs a reliable source of entropy |
||
| 282 | but entropy may need a lot of time to be collected therefore test systems could use no blocking entropy |
||
| 283 | sources like "/dev/urandom" that will allow quicker starts of Tomcat. |
||
| 284 | </p> |
||
| 285 | |||
| 286 | <p>The final step is to configure the Connector in the |
||
| 287 | <code>$CATALINA_BASE/conf/server.xml</code> file, where |
||
| 288 | <code>$CATALINA_BASE</code> represents the base directory for the |
||
| 289 | Tomcat instance. An example <code><Connector></code> element |
||
| 290 | for an SSL connector is included in the default <code>server.xml</code> |
||
| 291 | file installed with Tomcat. To configure an SSL connector that uses JSSE, you |
||
| 292 | will need to remove the comments and edit it so it looks something like |
||
| 293 | this:</p> |
||
| 294 | <div class="codeBox"><pre><code><!-- Define an SSL Coyote HTTP/1.1 Connector on port 8443 --> |
||
| 295 | <Connector |
||
| 296 | protocol="org.apache.coyote.http11.Http11NioProtocol" |
||
| 297 | port="8443" maxThreads="200" |
||
| 298 | maxParameterCount="1000" |
||
| 299 | scheme="https" secure="true" SSLEnabled="true" |
||
| 300 | keystoreFile="${user.home}/.keystore" keystorePass="changeit" |
||
| 301 | clientAuth="false" sslProtocol="TLS"/></code></pre></div> |
||
| 302 | <p> |
||
| 303 | Note: If tomcat-native is installed, the configuration will use JSSE with |
||
| 304 | an OpenSSL implementation, which supports either this configuration or the APR |
||
| 305 | configuration example given below.</p> |
||
| 306 | <p> |
||
| 307 | The APR connector uses different attributes for many SSL settings, |
||
| 308 | particularly keys and certificates. An example of an APR configuration is:</p> |
||
| 309 | <div class="codeBox"><pre><code><!-- Define an SSL Coyote HTTP/1.1 Connector on port 8443 --> |
||
| 310 | <Connector |
||
| 311 | protocol="org.apache.coyote.http11.Http11AprProtocol" |
||
| 312 | port="8443" maxThreads="200" |
||
| 313 | maxParameterCount="1000" |
||
| 314 | scheme="https" secure="true" SSLEnabled="true" |
||
| 315 | SSLCertificateFile="/usr/local/ssl/server.crt" |
||
| 316 | SSLCertificateKeyFile="/usr/local/ssl/server.pem" |
||
| 317 | SSLVerifyClient="optional" SSLProtocol="TLSv1+TLSv1.1+TLSv1.2"/></code></pre></div> |
||
| 318 | |||
| 319 | |||
| 320 | <p>The configuration options and information on which attributes |
||
| 321 | are mandatory, are documented in the SSL Support section of the |
||
| 322 | <a href="config/http.html#SSL_Support">HTTP connector</a> configuration |
||
| 323 | reference. Make sure that you use the correct attributes for the connector you |
||
| 324 | are using. The NIO and NIO2 connectors use JSSE unless the JSSE OpenSSL implementation is |
||
| 325 | installed (in which case it supports either the JSSE or OpenSSL configuration styles), |
||
| 326 | whereas the APR/native connector uses APR.</p> |
||
| 327 | |||
| 328 | <p>The <code>port</code> attribute is the TCP/IP |
||
| 329 | port number on which Tomcat will listen for secure connections. You can |
||
| 330 | change this to any port number you wish (such as to the default port for |
||
| 331 | <code>https</code> communications, which is 443). However, special setup |
||
| 332 | (outside the scope of this document) is necessary to run Tomcat on port |
||
| 333 | numbers lower than 1024 on many operating systems.</p> |
||
| 334 | |||
| 335 | <p><em>If you change the port number here, you should also change the |
||
| 336 | value specified for the <code>redirectPort</code> attribute on the |
||
| 337 | non-SSL connector. This allows Tomcat to automatically redirect |
||
| 338 | users who attempt to access a page with a security constraint specifying |
||
| 339 | that SSL is required, as required by the Servlet Specification.</em></p> |
||
| 340 | |||
| 341 | <p>After completing these configuration changes, you must restart Tomcat as |
||
| 342 | you normally do, and you should be in business. You should be able to access |
||
| 343 | any web application supported by Tomcat via SSL. For example, try:</p> |
||
| 344 | <div class="codeBox"><pre><code>https://localhost:8443/</code></pre></div> |
||
| 345 | <p>and you should see the usual Tomcat splash page (unless you have modified |
||
| 346 | the ROOT web application). If this does not work, the following section |
||
| 347 | contains some troubleshooting tips.</p> |
||
| 348 | |||
| 349 | </div></div> |
||
| 350 | |||
| 351 | </div><h3 id="Installing_a_Certificate_from_a_Certificate_Authority">Installing a Certificate from a Certificate Authority</h3><div class="text"> |
||
| 352 | <p>To obtain and install a Certificate from a Certificate Authority (like verisign.com, thawte.com |
||
| 353 | or trustcenter.de), read the previous section and then follow these instructions:</p> |
||
| 354 | |||
| 355 | <div class="subsection"><h4 id="Create_a_local_Certificate_Signing_Request_(CSR)">Create a local Certificate Signing Request (CSR)</h4><div class="text"> |
||
| 356 | <p>In order to obtain a Certificate from the Certificate Authority of your choice |
||
| 357 | you have to create a so called Certificate Signing Request (CSR). That CSR will be used |
||
| 358 | by the Certificate Authority to create a Certificate that will identify your website |
||
| 359 | as "secure". To create a CSR follow these steps:</p> |
||
| 360 | <ul> |
||
| 361 | <li>Create a local self-signed Certificate (as described in the previous section): |
||
| 362 | <div class="codeBox"><pre><code>keytool -genkey -alias tomcat -keyalg RSA |
||
| 363 | -keystore <your_keystore_filename></code></pre></div> |
||
| 364 | Note: In some cases you will have to enter the domain of your website (i.e. <code>www.myside.org</code>) |
||
| 365 | in the field "first- and lastname" in order to create a working Certificate. |
||
| 366 | </li> |
||
| 367 | <li>The CSR is then created with: |
||
| 368 | <div class="codeBox"><pre><code>keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr |
||
| 369 | -keystore <your_keystore_filename></code></pre></div> |
||
| 370 | </li> |
||
| 371 | </ul> |
||
| 372 | <p>Now you have a file called <code>certreq.csr</code> that you can submit to the Certificate Authority (look at the |
||
| 373 | documentation of the Certificate Authority website on how to do this). In return you get a Certificate.</p> |
||
| 374 | </div></div> |
||
| 375 | |||
| 376 | <div class="subsection"><h4 id="Importing_the_Certificate">Importing the Certificate</h4><div class="text"> |
||
| 377 | <p>Now that you have your Certificate you can import it into you local keystore. |
||
| 378 | First of all you have to import a so called Chain Certificate or Root Certificate into your keystore. |
||
| 379 | After that you can proceed with importing your Certificate.</p> |
||
| 380 | |||
| 381 | <ul> |
||
| 382 | <li>Download a Chain Certificate from the Certificate Authority you obtained the Certificate from.<br> |
||
| 383 | For Verisign.com commercial certificates go to: |
||
| 384 | http://www.verisign.com/support/install/intermediate.html<br> |
||
| 385 | For Verisign.com trial certificates go to: |
||
| 386 | http://www.verisign.com/support/verisign-intermediate-ca/Trial_Secure_Server_Root/index.html<br> |
||
| 387 | For Trustcenter.de go to: |
||
| 388 | http://www.trustcenter.de/certservices/cacerts/en/en.htm#server<br> |
||
| 389 | For Thawte.com go to: |
||
| 390 | http://www.thawte.com/certs/trustmap.html<br> |
||
| 391 | </li> |
||
| 392 | <li>Import the Chain Certificate into your keystore |
||
| 393 | <div class="codeBox"><pre><code>keytool -import -alias root -keystore <your_keystore_filename> |
||
| 394 | -trustcacerts -file <filename_of_the_chain_certificate></code></pre></div> |
||
| 395 | </li> |
||
| 396 | <li>And finally import your new Certificate |
||
| 397 | <div class="codeBox"><pre><code>keytool -import -alias tomcat -keystore <your_keystore_filename> |
||
| 398 | -file <your_certificate_filename></code></pre></div> |
||
| 399 | </li> |
||
| 400 | </ul> |
||
| 401 | |||
| 402 | <p>Each Certificate Authority tends to differ slightly from the others. They may |
||
| 403 | require slightly different information and/or provide the certificate and |
||
| 404 | associated certificate chain in different formats. Additionally, the rules that |
||
| 405 | the Certificate Authorities use for issuing certificates change over time. As a |
||
| 406 | result you may find that the commands given above may need to be modified. If |
||
| 407 | you require assistance then help is available via the |
||
| 408 | <a href="http://tomcat.apache.org/lists.html#tomcat-users">Apache Tomcat users |
||
| 409 | mailing list</a>.</p> |
||
| 410 | |||
| 411 | </div></div> |
||
| 412 | </div><h3 id="Using_OCSP_Certificates">Using OCSP Certificates</h3><div class="text"> |
||
| 413 | <p>To use Online Certificate Status Protocol (OCSP) with Apache Tomcat, ensure |
||
| 414 | you have downloaded, installed, and configured the |
||
| 415 | <a href="https://tomcat.apache.org/download-native.cgi"> |
||
| 416 | Tomcat Native Connector</a>. |
||
| 417 | Furthermore, if you use the Windows platform, ensure you download the |
||
| 418 | ocsp-enabled connector.</p> |
||
| 419 | <p>To use OCSP, you require the following:</p> |
||
| 420 | |||
| 421 | <ul> |
||
| 422 | <li>OCSP-enabled certificates</li> |
||
| 423 | <li>Tomcat with SSL APR connector</li> |
||
| 424 | <li>Configured OCSP responder</li> |
||
| 425 | </ul> |
||
| 426 | |||
| 427 | <div class="subsection"><h4 id="Generating_OCSP-Enabled_Certificates">Generating OCSP-Enabled Certificates</h4><div class="text"> |
||
| 428 | <p>Apache Tomcat requires the OCSP-enabled certificate to have the OCSP |
||
| 429 | responder location encoded in the certificate. The basic OCSP-related |
||
| 430 | certificate authority settings in the <code>openssl.cnf</code> file could look |
||
| 431 | as follows:</p> |
||
| 432 | |||
| 433 | <div class="codeBox"><pre><code> |
||
| 434 | #... omitted for brevity |
||
| 435 | |||
| 436 | [x509] |
||
| 437 | x509_extensions = v3_issued |
||
| 438 | |||
| 439 | [v3_issued] |
||
| 440 | subjectKeyIdentifier=hash |
||
| 441 | authorityKeyIdentifier=keyid,issuer |
||
| 442 | # The address of your responder |
||
| 443 | authorityInfoAccess = OCSP;URI:http://127.0.0.1:8088 |
||
| 444 | keyUsage = critical,digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment,keyAgreement,keyCertSign,cRLSign,encipherOnly,decipherOnly |
||
| 445 | basicConstraints=critical,CA:FALSE |
||
| 446 | nsComment="Testing OCSP Certificate" |
||
| 447 | |||
| 448 | #... omitted for brevity |
||
| 449 | </code></pre></div> |
||
| 450 | |||
| 451 | <p>The settings above encode the OCSP responder address |
||
| 452 | <code>127.0.0.1:8088</code> into the certificate. Note that for the following |
||
| 453 | steps, you must have <code>openssl.cnf</code> and other configuration of |
||
| 454 | your CA ready. To generate an OCSP-enabled certificate:</p> |
||
| 455 | |||
| 456 | <ul> |
||
| 457 | <li> |
||
| 458 | Create a private key: |
||
| 459 | <div class="codeBox"><pre><code>openssl genrsa -aes256 -out ocsp-cert.key 4096</code></pre></div> |
||
| 460 | </li> |
||
| 461 | <li> |
||
| 462 | Create a signing request (CSR): |
||
| 463 | <div class="codeBox"><pre><code>openssl req -config openssl.cnf -new -sha256 \ |
||
| 464 | -key ocsp-cert.key -out ocsp-cert.csr</code></pre></div></li> |
||
| 465 | <li> |
||
| 466 | Sign the CSR: |
||
| 467 | <div class="codeBox"><pre><code>openssl ca -openssl.cnf -extensions ocsp -days 375 -notext \ |
||
| 468 | -md sha256 -in ocsp-cert.csr -out ocsp-cert.crt</code></pre></div> |
||
| 469 | </li> |
||
| 470 | <li> |
||
| 471 | You may verify the certificate: |
||
| 472 | <div class="codeBox"><pre><code>openssl x509 -noout -text -in ocsp-cert.crt</code></pre></div> |
||
| 473 | </li> |
||
| 474 | </ul> |
||
| 475 | </div></div> |
||
| 476 | |||
| 477 | <div class="subsection"><h4 id="Configuring_OCSP_Connector">Configuring OCSP Connector</h4><div class="text"> |
||
| 478 | |||
| 479 | <p>To configure the OCSP connector, first verify that you are loading the Tomcat |
||
| 480 | APR library. Check the <a href="apr.html#Installation"> |
||
| 481 | Apache Portable Runtime (APR) based Native library for Tomcat</a> |
||
| 482 | for more information about installation of APR. A basic OCSP-enabled connector |
||
| 483 | definition in the <code>server.xml</code> file looks as follows:</p> |
||
| 484 | <div class="codeBox"><pre><code> |
||
| 485 | <Connector |
||
| 486 | port="8443" |
||
| 487 | protocol="org.apache.coyote.http11.Http11AprProtocol" |
||
| 488 | maxParameterCount="1000" |
||
| 489 | secure="true" |
||
| 490 | scheme="https" |
||
| 491 | SSLEnabled="true" |
||
| 492 | <SSLHostConfig |
||
| 493 | caCertificateFile="/path/to/ca.pem" |
||
| 494 | certificateVerification="require" |
||
| 495 | certificateVerificationDepth="10" > |
||
| 496 | <Certificate |
||
| 497 | certificateFile="/path/to/ocsp-cert.crt" |
||
| 498 | certificateKeyFile="/path/to/ocsp-cert.key" /> |
||
| 499 | </SSLHostConfig> |
||
| 500 | </code></pre></div> |
||
| 501 | </div></div> |
||
| 502 | |||
| 503 | <div class="subsection"><h4 id="Starting_OCSP_Responder">Starting OCSP Responder</h4><div class="text"> |
||
| 504 | <p>Apache Tomcat will query an OCSP responder server to get the certificate |
||
| 505 | status. When testing, an easy way to create an OCSP responder is by executing |
||
| 506 | the following: |
||
| 507 | <div class="codeBox"><pre><code>openssl ocsp -port 127.0.0.1:8088 \ |
||
| 508 | -text -sha256 -index index.txt \ |
||
| 509 | -CA ca-chain.cert.pem -rkey ocsp-cert.key \ |
||
| 510 | -rsigner ocsp-cert.crt</code></pre></div> </p> |
||
| 511 | |||
| 512 | <p>Do note that when using OCSP, the responder encoded in the connector |
||
| 513 | certificate must be running. For further information, see |
||
| 514 | <a href="https://www.openssl.org/docs/man1.1.0/apps/ocsp.html"> |
||
| 515 | OCSP documentation |
||
| 516 | </a>. |
||
| 517 | </p> |
||
| 518 | |||
| 519 | </div></div> |
||
| 520 | |||
| 521 | </div><h3 id="Troubleshooting">Troubleshooting</h3><div class="text"> |
||
| 522 | |||
| 523 | <p>Additional information may be obtained about TLS handshake failures by |
||
| 524 | configuring the dedicated TLS handshake logger to log debug level messages by |
||
| 525 | adding the following to <code>$CATALINA_BASE/conf/logging.properties</code>: |
||
| 526 | <div class="codeBox"><pre><code>org.apache.tomcat.util.net.NioEndpoint.handshake.level=FINE</code></pre></div> |
||
| 527 | or |
||
| 528 | <div class="codeBox"><pre><code>org.apache.tomcat.util.net.Nio2Endpoint.handshake.level=FINE</code></pre></div> |
||
| 529 | depending on the <strong>Connector</strong> being used. |
||
| 530 | </p> |
||
| 531 | |||
| 532 | <p>Here is a list of common problems that you may encounter when setting up |
||
| 533 | SSL communications, and what to do about them.</p> |
||
| 534 | |||
| 535 | <ul> |
||
| 536 | |||
| 537 | <li>When Tomcat starts up, I get an exception like |
||
| 538 | "java.io.FileNotFoundException: {some-directory}/{some-file} not found". |
||
| 539 | |||
| 540 | <p>A likely explanation is that Tomcat cannot find the keystore file |
||
| 541 | where it is looking. By default, Tomcat expects the keystore file to |
||
| 542 | be named <code>.keystore</code> in the user home directory under which |
||
| 543 | Tomcat is running (which may or may not be the same as yours :-). If |
||
| 544 | the keystore file is anywhere else, you will need to add a |
||
| 545 | <code>keystoreFile</code> attribute to the <code><Connector></code> |
||
| 546 | element in the <a href="#Edit_the_Tomcat_Configuration_File">Tomcat |
||
| 547 | configuration file</a>.</p> |
||
| 548 | </li> |
||
| 549 | |||
| 550 | <li>When Tomcat starts up, I get an exception like |
||
| 551 | "java.io.FileNotFoundException: Keystore was tampered with, or |
||
| 552 | password was incorrect". |
||
| 553 | |||
| 554 | <p>Assuming that someone has not <em>actually</em> tampered with |
||
| 555 | your keystore file, the most likely cause is that Tomcat is using |
||
| 556 | a different password than the one you used when you created the |
||
| 557 | keystore file. To fix this, you can either go back and |
||
| 558 | <a href="#Prepare_the_Certificate_Keystore">recreate the keystore |
||
| 559 | file</a>, or you can add or update the <code>keystorePass</code> |
||
| 560 | attribute on the <code><Connector></code> element in the |
||
| 561 | <a href="#Edit_the_Tomcat_Configuration_File">Tomcat configuration |
||
| 562 | file</a>. <strong>REMINDER</strong> - Passwords are case sensitive!</p> |
||
| 563 | </li> |
||
| 564 | |||
| 565 | <li>When Tomcat starts up, I get an exception like |
||
| 566 | "java.net.SocketException: SSL handshake error javax.net.ssl.SSLException: No |
||
| 567 | available certificate or key corresponds to the SSL cipher suites which are |
||
| 568 | enabled." |
||
| 569 | |||
| 570 | <p>A likely explanation is that Tomcat cannot find the alias for the server |
||
| 571 | key within the specified keystore. Check that the correct |
||
| 572 | <code>keystoreFile</code> and <code>keyAlias</code> are specified in the |
||
| 573 | <code><Connector></code> element in the |
||
| 574 | <a href="#Edit_the_Tomcat_Configuration_File">Tomcat configuration file</a>. |
||
| 575 | <strong>REMINDER</strong> - <code>keyAlias</code> values may be case |
||
| 576 | sensitive!</p> |
||
| 577 | </li> |
||
| 578 | |||
| 579 | <li>My Java-based client aborts handshakes with exceptions such as |
||
| 580 | "java.lang.RuntimeException: Could not generate DH keypair" and |
||
| 581 | "java.security.InvalidAlgorithmParameterException: Prime size must be multiple |
||
| 582 | of 64, and can only range from 512 to 1024 (inclusive)" |
||
| 583 | |||
| 584 | <p>If you are using the APR/native connector or the JSSE OpenSSL implementation, |
||
| 585 | it will determine the strength of ephemeral DH keys from the key size of |
||
| 586 | your RSA certificate. For example a 2048 bit RSA key will result in |
||
| 587 | using a 2048 bit prime for the DH keys. Unfortunately Java 6 only supports |
||
| 588 | 768 bit and Java 7 only supports 1024 bit. So if your certificate has a |
||
| 589 | stronger key, old Java clients might produce such handshake failures. |
||
| 590 | As a mitigation you can either try to force them to use another cipher by |
||
| 591 | configuring an appropriate <code>SSLCipherSuite</code> and activate |
||
| 592 | <code>SSLHonorCipherOrder</code>, or embed weak DH params in your |
||
| 593 | certificate file. The latter approach is not recommended because it weakens |
||
| 594 | the SSL security (logjam attack).</p> |
||
| 595 | </li> |
||
| 596 | |||
| 597 | </ul> |
||
| 598 | |||
| 599 | <p>If you are still having problems, a good source of information is the |
||
| 600 | <strong>TOMCAT-USER</strong> mailing list. You can find pointers to archives |
||
| 601 | of previous messages on this list, as well as subscription and unsubscription |
||
| 602 | information, at |
||
| 603 | <a href="https://tomcat.apache.org/lists.html">https://tomcat.apache.org/lists.html</a>.</p> |
||
| 604 | |||
| 605 | </div><h3 id="Using_the_SSL_for_session_tracking_in_your_application">Using the SSL for session tracking in your application</h3><div class="text"> |
||
| 606 | <p>This is a new feature in the Servlet 3.0 specification. Because it uses the |
||
| 607 | SSL session ID associated with the physical client-server connection there |
||
| 608 | are some limitations. They are:</p> |
||
| 609 | <ul> |
||
| 610 | <li>Tomcat must have a connector with the attribute |
||
| 611 | <strong>isSecure</strong> set to <code>true</code>.</li> |
||
| 612 | <li>If SSL connections are managed by a proxy or a hardware accelerator |
||
| 613 | they must populate the SSL request headers (see the |
||
| 614 | <a href="config/valve.html">SSLValve</a>) so that |
||
| 615 | the SSL session ID is visible to Tomcat.</li> |
||
| 616 | <li>If Tomcat terminates the SSL connection, it will not be possible to use |
||
| 617 | session replication as the SSL session IDs will be different on each |
||
| 618 | node.</li> |
||
| 619 | </ul> |
||
| 620 | |||
| 621 | <p> |
||
| 622 | To enable SSL session tracking you need to use a context listener to set the |
||
| 623 | tracking mode for the context to be just SSL (if any other tracking mode is |
||
| 624 | enabled, it will be used in preference). It might look something like:</p> |
||
| 625 | <div class="codeBox"><pre><code>package org.apache.tomcat.example; |
||
| 626 | |||
| 627 | import java.util.EnumSet; |
||
| 628 | |||
| 629 | import javax.servlet.ServletContext; |
||
| 630 | import javax.servlet.ServletContextEvent; |
||
| 631 | import javax.servlet.ServletContextListener; |
||
| 632 | import javax.servlet.SessionTrackingMode; |
||
| 633 | |||
| 634 | public class SessionTrackingModeListener implements ServletContextListener { |
||
| 635 | |||
| 636 | @Override |
||
| 637 | public void contextDestroyed(ServletContextEvent event) { |
||
| 638 | // Do nothing |
||
| 639 | } |
||
| 640 | |||
| 641 | @Override |
||
| 642 | public void contextInitialized(ServletContextEvent event) { |
||
| 643 | ServletContext context = event.getServletContext(); |
||
| 644 | EnumSet<SessionTrackingMode> modes = |
||
| 645 | EnumSet.of(SessionTrackingMode.SSL); |
||
| 646 | |||
| 647 | context.setSessionTrackingModes(modes); |
||
| 648 | } |
||
| 649 | |||
| 650 | }</code></pre></div> |
||
| 651 | |||
| 652 | <p>Note: SSL session tracking is implemented for the NIO and NIO2 connectors. |
||
| 653 | It is not yet implemented for the APR connector.</p> |
||
| 654 | |||
| 655 | </div><h3 id="Miscellaneous_Tips_and_Bits">Miscellaneous Tips and Bits</h3><div class="text"> |
||
| 656 | |||
| 657 | <p>To access the SSL session ID from the request, use:</p> |
||
| 658 | |||
| 659 | <div class="codeBox"><pre><code>String sslID = (String)request.getAttribute("javax.servlet.request.ssl_session_id");</code></pre></div> |
||
| 660 | <p> |
||
| 661 | For additional discussion on this area, please see |
||
| 662 | <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=22679">Bugzilla</a>. |
||
| 663 | </p> |
||
| 664 | |||
| 665 | <p>To terminate an SSL session, use:</p> |
||
| 666 | <div class="codeBox"><pre><code>// Standard HTTP session invalidation |
||
| 667 | session.invalidate(); |
||
| 668 | |||
| 669 | // Invalidate the SSL Session |
||
| 670 | org.apache.tomcat.util.net.SSLSessionManager mgr = |
||
| 671 | (org.apache.tomcat.util.net.SSLSessionManager) |
||
| 672 | request.getAttribute("javax.servlet.request.ssl_session_mgr"); |
||
| 673 | mgr.invalidateSession(); |
||
| 674 | |||
| 675 | // Close the connection since the SSL session will be active until the connection |
||
| 676 | // is closed |
||
| 677 | response.setHeader("Connection", "close");</code></pre></div> |
||
| 678 | <p> |
||
| 679 | Note that this code is Tomcat specific due to the use of the |
||
| 680 | SSLSessionManager class. This is currently only available for the NIO and |
||
| 681 | NIO2 connectors, not the APR/native connector. |
||
| 682 | </p> |
||
| 683 | </div></div></div></div></div><footer><div id="footer"> |
||
| 684 | Copyright © 1999-2025, The Apache Software Foundation |
||
| 685 | <br> |
||
| 686 | Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo |
||
| 687 | are either registered trademarks or trademarks of the Apache Software |
||
| 688 | Foundation. |
||
| 689 | </div></footer></div></body></html> |