Author: markt
Date: Sun Sep 20 23:14:57 2009
New Revision: 817121
URL: http://svn.apache.org/viewvc?rev=817121&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/tc6.0.x/trunk/webapps/docs/ssl-howto.xml
Modified: tomcat/tc6.0.x/trunk/webapps/docs/ssl-howto.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/ssl-howto.xml?rev=817121&r1=817120&r2=817121&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/ssl-howto.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/ssl-howto.xml Sun Sep 20 23:14:57 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,20 +280,58 @@
</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"
SSLEngine="someengine" SSLRandomSeed="somedevice" />
+<Listener className="org.apache.catalina.core.AprLifecycleListener"
+ SSLEngine="someengine" SSLRandomSeed="somedevice" />
</source>
The default value is
<source>
-<Listener className="org.apache.catalina.core.AprLifecycleListener"
SSLEngine="on" SSLRandomSeed="builtin" />
+<Listener className="org.apache.catalina.core.AprLifecycleListener"
+ SSLEngine="on" SSLRandomSeed="builtin" />
</source>
So to use SSL under APR, make sure the SSLEngine attribute is set to something
other than <code>off</code>.
The default value is <code>on</code> and if you specify another value, it has
to be a valid engine name.
<br/>
If you haven't compiled in SSL support into your Tomcat Native library, then
you can turn this initialization off
<source>
-<Listener className="org.apache.catalina.core.AprLifecycleListener"
SSLEngine="off" />
+<Listener className="org.apache.catalina.core.AprLifecycleListener"
+ SSLEngine="off" />
</source>
SSLRandomSeed allows to specify a source of entropy. Productive system needs a
reliable source of entropy
but entropy may need a lot of time to be collected therefore test systems
could use no blocking entropy
@@ -303,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" maxSpareThreads="75"
- 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"/>
@@ -323,66 +357,21 @@
</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" maxSpareThreads="75"
- 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>
- 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" maxSpareThreads="75"
- 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" maxSpareThreads="75"
- 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" maxSpareThreads="75"
- 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>You will note that the Connector element itself is commented out by default,
so you will need to remove the comment tags around it. Then, you can
customize the specified attributes as necessary. For detailed information
@@ -403,110 +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
@@ -534,14 +430,14 @@
as "secure". To create a CSR follow these steps:</p>
<ul>
<li>Create a local Certificate (as described in the previous section):
- <source>keytool -genkey -alias tomcat -keyalg RSA \
- -keystore <your_keystore_filename></source>
- Note: In some cases you will have to enter the domain of your website
(i.e. <code>www.myside.org</code>)
- in the field "first- and lastname" in order to create a working
Certificate.
+ <source>keytool -genkey -alias tomcat -keyalg RSA \
+ -keystore <your_keystore_filename></source>
+ Note: In some cases you will have to enter the domain of your website
(i.e. <code>www.myside.org</code>)
+ in the field "first- and lastname" in order to create a working
Certificate.
</li>
<li>The CSR is then created with:
- <source>keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr \
- -keystore <your_keystore_filename></source>
+ <source>keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr \
+ -keystore <your_keystore_filename></source>
</li>
</ul>
<p>Now you have a file called <code>certreq.csr</code> that you can submit to
the Certificate Authority (look at the
@@ -555,22 +451,22 @@
<ul>
<li>Download a Chain Certificate from the Certificate Authority you obtained
the Certificate from.<br/>
- For Verisign.com commercial certificates go to:
+ For Verisign.com commercial certificates go to:
http://www.verisign.com/support/install/intermediate.html<br/>
For Verisign.com trial certificates go to:
http://www.verisign.com/support/verisign-intermediate-ca/Trial_Secure_Server_Root/index.html<br/>
- For Trustcenter.de go to:
+ For Trustcenter.de go to:
http://www.trustcenter.de/certservices/cacerts/en/en.htm#server<br/>
- For Thawte.com go to:
+ For Thawte.com go to:
http://www.thawte.com/certs/trustmap.html<br/>
</li>
<li>Import the Chain Certificate into your keystore
<source>keytool -import -alias root -keystore
<your_keystore_filename> \
- -trustcacerts -file <filename_of_the_chain_certificate></source>
+ -trustcacerts -file <filename_of_the_chain_certificate></source>
</li>
<li>And finally import your new Certificate
- <source>keytool -import -alias tomcat -keystore
<your_keystore_filename> \
- -file <your_certificate_filename></source>
+ <source>keytool -import -alias tomcat -keystore
<your_keystore_filename> \
+ -file <your_certificate_filename></source>
</li>
</ul>
</subsection>
@@ -653,8 +549,9 @@
For additional discussion on this area, please see
<a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=22679";>Bugzilla</a>.
</p>
+
</section>
</body>
-</document>
+</document>
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
