Author: markt
Date: Sun Sep 20 23:10:15 2009
New Revision: 817120
URL: http://svn.apache.org/viewvc?rev=817120&view=rev
Log:
Fix https://issues.apache.org/bugzilla/show_bug.cgi?id=47231
Improve the SSL docs. Based on a patch by Sebb.
Remove duplication of configuration parameters - it is better to reference the
config docs to prevent the two lists of attributes getting out of sync.
Modified:
tomcat/trunk/webapps/docs/ssl-howto.xml
Modified: tomcat/trunk/webapps/docs/ssl-howto.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/ssl-howto.xml?rev=817120&r1=817119&r2=817120&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/ssl-howto.xml (original)
+++ tomcat/trunk/webapps/docs/ssl-howto.xml Sun Sep 20 23:10:15 2009
@@ -33,10 +33,6 @@
<section name="Quick Start">
- <p><b>IMPORTANT NOTE: This Howto refers to usage of JSSE, that comes
included with
- jdk 1.5 and higher. When using APR, Tomcat will
- use OpenSSL, which uses a different configuration.</b></p>
-
<blockquote><em>
<p>The description below uses the variable name $CATALINA_BASE to refer the
base directory against which most relative paths are resolved. If you have
@@ -60,7 +56,8 @@
<p></p>
and specify a password value of "changeit".</li><br/><br/>
<li>Uncomment the "SSL HTTP/1.1 Connector" entry in
- <code>$CATALINA_BASE/conf/server.xml</code> and tweak as necessary.</li>
+ <code>$CATALINA_BASE/conf/server.xml</code> and modify as described in
+ the <a href="#Configuration">Configuration section</a> below.</li>
<br/><br/>
</ol>
@@ -267,6 +264,7 @@
password specifically for this Certificate (as opposed to any other
Certificates stored in the same keystore file). You <strong>MUST</strong>
use the same password here as was used for the keystore password itself.
+This is a restriction of the Tomcat implementation.
(Currently, the <code>keytool</code> prompt will tell you that pressing the
ENTER key does this for you automatically.)</p>
@@ -282,6 +280,41 @@
</subsection>
<subsection name="Edit the Tomcat Configuration File">
+<p>
+Tomcat can use two different implementations of SSL:
+<ul>
+<li>the JSSE implementation provided as part of the Java runtime (since
1.4)</li>
+<li>the APR implementation, which uses the OpenSSL engine by default.</li>
+</ul>
+The exact configuration details depend on which implementation is being used.
+The implementation used by Tomcat is chosen automatically unless it is
overriden as described below.
+If the installation uses <a href="apr.html">APR</a>
+- i.e. you have installed the Tomcat native library -
+then it will use the APR SSL implementation, otherwise it will use the Java
JSSE implementation.
+</p>
+
+<p>
+ To avoid auto configuration you can define which implementation to use by
specifying a classname
+ in the <b>protocol</b> attribute of the Connector.<br/>
+ To define a Java (JSSE) connector, regardless of whether the APR library is
loaded or not do:
+<source>
+<-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
+<Connector protocol="org.apache.coyote.http11.Http11Protocol"
+ port="8443" .../>
+
+<-- Define a non-blocking Java SSL Coyote HTTP/1.1 Connector on port 8443
-->
+<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
+ port="8443" .../>
+</source>
+Alternatively, to specify an APR connector (the APR library must be available)
use:
+<source>
+<-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 -->
+<Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
+ port="8443" .../>
+</source>
+
+</p>
+
<p>If you are using APR, you have the option of configuring an alternative
engine to OpenSSL.
<source>
<Listener className="org.apache.catalina.core.AprLifecycleListener"
@@ -306,19 +339,17 @@
</p>
-<p>The final step is to configure your secure socket in the
+<p>The final step is to configure the Connector in the
<code>$CATALINA_BASE/conf/server.xml</code> file, where
<code>$CATALINA_BASE</code> represents the base directory for the
Tomcat 6 instance. An example <code><Connector></code> element
for an SSL connector is included in the default <code>server.xml</code>
-file installed with Tomcat. It will look something like this:</p>
+file installed with Tomcat. For JSSE, it should look something like this:</p>
<source>
<-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!--
<Connector
- port="8443" minSpareThreads="5"
- enableLookups="true" disableUploadTimeout="true"
- acceptCount="100" maxThreads="200"
+ port="8443" maxThreads="200"
scheme="https" secure="true" SSLEnabled="true"
keystoreFile="${user.home}/.keystore" keystorePass="changeit"
clientAuth="false" sslProtocol="TLS"/>
@@ -326,64 +357,19 @@
</source>
<p>
The example above will throw an error if you have the APR and the Tomcat
Native libraries in your path,
- as tomcat will try to autoload the APR connector. The APR connector uses
different attributes for
- SSL keys and certificates. An example of such configuration would be
+ as Tomcat will try to use the APR connector. The APR connector uses
different attributes for
+ SSL keys and certificates. An example of an APR configuration is:
<source>
<-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!--
<Connector
- port="8443" minSpareThreads="5"
- enableLookups="true" disableUploadTimeout="true"
- acceptCount="100" maxThreads="200"
- scheme="https" secure="true" SSLEnabled="true"
- SSLCertificateFile="/usr/local/ssl/server.crt"
- SSLCertificateKeyFile="/usr/local/ssl/server.pem"
- clientAuth="false" sslProtocol="TLS"/>
--->
-</source>
-</p>
-
-<p>
- To avoid auto configuration you can define which connector to use by
specifying a classname
- in the protocol attribute.<br/>
- To define a Java connector, regardless if the APR library is loaded or not
do:
-<source>
-<-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
-<!--
-<Connector protocol="org.apache.coyote.http11.Http11Protocol"
- port="8443" minSpareThreads="5"
- enableLookups="true" disableUploadTimeout="true"
- acceptCount="100" maxThreads="200"
- scheme="https" secure="true" SSLEnabled="true"
- keystoreFile="${user.home}/.keystore" keystorePass="changeit"
- clientAuth="false" sslProtocol="TLS"/>
--->
-<-- Define a non-blocking Java SSL Coyote HTTP/1.1 Connector on port 8443
-->
-<!--
-<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
- port="8443" minSpareThreads="5"
- enableLookups="true" disableUploadTimeout="true"
- acceptCount="100" maxThreads="200"
- scheme="https" secure="true" SSLEnabled="true"
- keystoreFile="${user.home}/.keystore" keystorePass="changeit"
- clientAuth="false" sslProtocol="TLS"/>
--->
-</source>
-and to specify an APR connector
-<source>
-<-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 -->
-<!--
-<Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
- port="8443" minSpareThreads="5"
- enableLookups="true" disableUploadTimeout="true"
- acceptCount="100" maxThreads="200"
+ port="8443" maxThreads="200"
scheme="https" secure="true" SSLEnabled="true"
SSLCertificateFile="/usr/local/ssl/server.crt"
SSLCertificateKeyFile="/usr/local/ssl/server.pem"
- clientAuth="false" sslProtocol="TLS"/>
+ clientAuth="optional" SSLProtocol="TLSv1"/>
-->
</source>
-
</p>
<p>You will note that the Connector element itself is commented out by default,
@@ -406,111 +392,17 @@
value specified for the <code>redirectPort</code> attribute on the
non-SSL connector. This allows Tomcat to automatically redirect
users who attempt to access a page with a security constraint specifying
- that SSL is required, as required by the Servlet 2.4 Specification.</p>
+ that SSL is required, as required by the Servlet Specification.</p>
</em></blockquote>
-<p>There are additional options used to configure the SSL protocol.
- You may need to add or change the following attribute
-values, depending on how you configured your keystore earlier:</p>
-
-<table border="1">
- <tr>
- <th>Attribute</th>
- <th>Description</th>
- </tr>
- <tr>
- <td><code>clientAuth</code></td>
- <td>Set this value to <code>true</code> if you want Tomcat to require
- all SSL clients to present a client Certificate in order to use
- this socket. Set this value to <code>want</code> if you want Tomcat
- to request a client Certificate, but not fail if one isn't presented.
- A <code>false</code> value (which is the default) will not require a
- certificate chain unless the client requests a resource protected by a
- security constraint that uses <code>CLIENT-CERT</code> authentication.
- </td>
- </tr>
- <tr><td><code>SSLEnabled</code></td>
- <td>
- Use this attribute to enable SSL traffic on a connector.
- To turn on SSL handshake/encryption/decryption on a connector
- set this value to <code>true</code>.
- The default value is <code>false</code>.
- When turning this value <code>true</code> you will want to set the
- <code>scheme</code> and the <code>secure</code> attributes as well
- to pass the correct <code>request.getScheme()</code> and
- <code>request.isSecure()</code> values to the servlets
- </td>
- </tr>
- <tr>
- <td><code>keystoreFile</code></td>
- <td>Add this attribute if the keystore file you created is not in
- the default place that Tomcat expects (a file named
- <code>.keystore</code> in the user home directory under
- which Tomcat is running). You can specify an absolute pathname,
- or a relative pathname that is resolved against the
- <code>$CATALINA_BASE</code> environment variable.</td>
- </tr>
- <tr>
- <td><code>keystorePass</code></td>
- <td>Add this element if you used a different keystore (and Certificate)
- password than the one Tomcat expects (<code>changeit</code>).</td>
- </tr>
- <tr>
- <td><code>keystoreType</code></td>
- <td>Add this element if using a keystore type other than <code>JKS</code>.
- For example the *.p12 files from OpenSSL can be used using
<code>PKCS12</code>.</td>
- </tr>
- <tr>
- <td><code>sslProtocol</code></td>
- <td>The encryption/decryption protocol to be used on this socket.
- It is not recommended to change this value if you are using Sun's
- JVM. It is reported that IBM's 1.4.1 implementation
- of the TLS protocol is not compatible with some popular browsers.
- In this case, use the value <code>SSL</code>.</td>
- </tr>
- <tr>
- <td><code>ciphers</code></td>
- <td>The comma separated list of encryption ciphers that this socket is
- allowed to use. By default, the default ciphers for the JVM will be
- used. Note that this usually means that the weak export grade ciphers
- will be included in the list of available ciphers. The ciphers are
- specified using the JSSE cipher naming convention.</td>
- </tr>
- <tr>
- <td><code>algorithm</code></td>
- <td>The <code>X509</code> algorithm to use. This defaults to the Sun
- implementation (<code>SunX509</code>). For IBM JVMs you should use
- the value <code>IbmX509</code>. For other vendors, consult the JVM
- documentation for the correct value.
- </td>
- </tr>
- <tr>
- <td><code>truststoreFile</code></td>
- <td>The TrustStore file to use to validate client certificates.</td>
- </tr>
- <tr>
- <td><code>truststorePass</code></td>
- <td>The password to access the TrustStore. This defaults to the value
- of <code>keystorePass</code>.</td>
- </tr>
- <tr>
- <td><code>truststoreType</code></td>
- <td>Add this element if your are using a different format for the
- TrustStore then you are using for the KeyStore.</td>
- </tr>
- <tr>
- <td><code>keyAlias</code></td>
- <td>Add this element if your have more than one key in the KeyStore.
- If the element is not present the first key read in the KeyStore
- will be used.</td>
- </tr>
- <tr>
- <td><code>crlFile</code></td>
- <td>The certificate revocation list file to use to validate client
- certificates.</td>
- </tr>
-
-</table>
+<p>There are additional options used to configure the SSL protocol. You may
+need to add or change some attributes, depending on how you configured your
+keystore earlier. If you are using a Java JSSE based SSL connector then
+configuration options are documented in the
+<a href="config/http.html">Java HTTP connector</a> configuration
+reference. If you are using the APR/native connector then refer to the
+<a href="apr.html">APR connector</a> configuration guide for details of the
+available configuration options.</p>
<p>After completing these configuration changes, you must restart Tomcat as
you normally do, and you should be in business. You should be able to access
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
