tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ma...@apache.org
Subject svn commit: r817120 - /tomcat/trunk/webapps/docs/ssl-howto.xml
Date Sun, 20 Sep 2009 23:10:15 GMT
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>
+&lt;-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
+&lt;Connector protocol="org.apache.coyote.http11.Http11Protocol"
+           port="8443" .../&gt;
+
+&lt;-- Define a non-blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
+&lt;Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
+           port="8443" .../&gt;
+</source>
+Alternatively, to specify an APR connector (the APR library must be available) use:
+<source>
+&lt;-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
+&lt;Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
+           port="8443" .../&gt;
+</source>
+
+</p>
+
 <p>If you are using APR, you have the option of configuring an alternative engine to
OpenSSL.
 <source>
 &lt;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>&lt;Connector&gt;</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>
 &lt;-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
 &lt;!--
 &lt;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"/&gt;
@@ -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>
 &lt;-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
 &lt;!--
 &lt;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"/&gt;
---&gt;
-</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>
-&lt;-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
-&lt;!--
-&lt;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"/&gt;
---&gt;
-&lt;-- Define a non-blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
-&lt;!--
-&lt;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"/&gt;
---&gt;
-</source>
-and to specify an APR connector
-<source>
-&lt;-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 --&gt;
-&lt;!--
-&lt;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"/&gt;
+           clientAuth="optional" SSLProtocol="TLSv1"/&gt;
 --&gt;
 </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-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org


Mime
View raw message