Author: remm
Date: Wed Feb 10 16:31:51 2016
New Revision: 1729644
URL: http://svn.apache.org/viewvc?rev=1729644&view=rev
Log:
Update SSL documentation.
Modified:
tomcat/trunk/webapps/docs/apr.xml
tomcat/trunk/webapps/docs/config/http.xml
tomcat/trunk/webapps/docs/ssl-howto.xml
Modified: tomcat/trunk/webapps/docs/apr.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/apr.xml?rev=1729644&r1=1729643&r2=1729644&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/apr.xml (original)
+++ tomcat/trunk/webapps/docs/apr.xml Wed Feb 10 16:31:51 2016
@@ -90,7 +90,7 @@
</p>
<ul>
<li>APR 1.2+ development headers (libapr1-dev package)</li>
- <li>OpenSSL 0.9.7+ development headers (libssl-dev package)</li>
+ <li>OpenSSL 1.0.2+ development headers (libssl-dev package)</li>
<li>JNI headers from Java compatible JDK 1.4+</li>
<li>GNU development environment (gcc, make)</li>
</ul>
@@ -132,6 +132,14 @@
<section name="APR Lifecycle Listener Configuration">
<subsection name="AprLifecycleListener">
<attributes>
+ <attribute name="FIPSMode" required="false">
+ <p>
+ Allows using OpenSSL FIPS mode. If set to <code>on</code>, Tomcat will
enter FIPS mode if needed.
+ If set to <code>require</code>, Tomcat will fail to start if FIPS mode
was not active. If set
+ to <code>enter</code>, Tomcat will enter FIPS mode and will cause an
error if FIPS mode was active.
+ If unset or set to <code>off</code>, Tomcat will not check FIPS status.
+ </p>
+ </attribute>
<attribute name="SSLEngine" required="false">
<p>
Name of the SSLEngine to use. off: Do not use SSL, on: Use SSL but no
specific ENGINE.
@@ -145,6 +153,17 @@
website</a> for more details on SSL hardware engines and manufacturers.
</p>
</attribute>
+ <attribute name="SSLRandomSeed" required="false">
+ <p>
+ If specified, this sets a random source that will be used by OpenSSL.
+ </p>
+ </attribute>
+ <attribute name="useAprConnector" required="false">
+ <p>
+ Set to <code>true</code> to use the APR connector by default. The
default value is
+ <code>false</code>, which will use the NIO connector with the JSSE
OpenSSL implementation instead.
+ </p>
+ </attribute>
</attributes>
</subsection>
</section>
Modified: tomcat/trunk/webapps/docs/config/http.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/config/http.xml?rev=1729644&r1=1729643&r2=1729644&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/config/http.xml (original)
+++ tomcat/trunk/webapps/docs/config/http.xml Wed Feb 10 16:31:51 2016
@@ -172,10 +172,12 @@
either a Java NIO based connector or an APR/native based connector.
If the <code>PATH</code> (Windows) or <code>LD_LIBRARY_PATH</code> (on
most unix systems) environment variables contain the Tomcat native
- library, the APR/native connector will be used. If the native library
- cannot be found, the Java NIO based connector will be used. Note
- that the APR/native connector has different settings for HTTPS than the
- Java connectors.<br/>
+ library, and the <code>AprLifecycleListener</code> that is used to
+ initialize APR has its <code>useAprConnector</code> attribute set to
+ <code>true</code>, the APR/native connector will be used. If the
native library
+ cannot be found or the attribute is not configured, the Java NIO based
+ connector will be used. Note that the APR/native connector has
different
+ settings for HTTPS than the Java connectors.<br/>
To use an explicit protocol rather than rely on the auto-switching
mechanism described above, the following values may be used:<br/>
<code>org.apache.coyote.http11.Http11NioProtocol</code> -
@@ -987,12 +989,14 @@
attributes to the values <code>https</code> and <code>true</code>
respectively, to pass correct information to the servlets.</p>
- <p>The NIO and NIO2 connectors use the JSSE SSL implementation whereas the
- APR/native connector uses OpenSSL. Prior to Tomcat 9, different configuration
+ <p>The NIO and NIO2 connectors use either the JSSE Java SSL implementation or
+ an OpenSSL implementation, whereas the
+ APR/native connector uses OpenSSL only. Prior to Tomcat 9, different
configuration
attributes were used for JSSE and OpenSSL. From Tomcat 9 onwards, and as far
as possible, common configuration attributes are used for both JSSE and
- OpenSSL. This is to aid simpler switching between connector implementations
- for SSL connectors.</p>
+ OpenSSL. Also if using the JSSE OpenSSL implementation, configuration can be
set using
+ either the JSSE or APR attributes (note: but not both types within the same
configuration).
+ This is to aid simpler switching between connector implementations for SSL
connectors.</p>
<p>Each secure connector must define at least one
<strong>SSLHostConfig</strong>. The names of the
@@ -1357,6 +1361,10 @@
<subsection name="SSL Support - Connector - NIO and NIO2">
+ <p>When APR/native is enabled, the connectors will default to using OpenSSL
through JSSE,
+ which may be more optimized than the JSSE Java implementation depending on
the processor being used,
+ and can be complemented with many commercial accelerator components.</p>
+
<p>The following NIO and NIO2 SSL configuration attributes are not specific
to
a virtual host and, therefore, must be configured on the connector.</p>
@@ -1367,7 +1375,7 @@
message received on a new TLS connection (the client hello) to extract
the
requested server name. The message needs to be buffered so it can then be
passed to the JSSE implementation for normal TLS processing. In theory,
- this first message could be very large although in practise it is
+ this first message could be very large although in practice it is
typically a few hundred bytes. This attribute sets the maximum message
size that Tomcat will buffer. If a message exceeds this size, the
connection will be configured as if no server name was indicated by the
@@ -1376,13 +1384,15 @@
</attribute>
<attribute name="sslImplementationName" required="false">
- <p>The class name of the SSL implementation to use. If not specified, the
+ <p>The class name of the SSL implementation to use. If not specified and
+ the tomcat-native library is not installed, the
default of
<code>org.apache.tomcat.util.net.jsse.JSSEImplementation</code>
will be used which wraps JVM's default JSSE provider. Note that the
JVM can be configured to use a different JSSE provider as the default.
Tomcat also bundles a special SSL implementation for JSSE that is backed
by OpenSSL. To enable it, the native library should be enabled as if
- intending to use the APR connector, the value of this attribute should be
+ intending to use the APR connector, and Tomcat will automatically enable
it
+ and the default value of this attribute becomes
<code>org.apache.tomcat.util.net.openssl.OpenSSLImplementation</code>.
In that case, the attributes from either from either JSSE and OpenSSL
configuration styles can be used, as long as the two types are not mixed
@@ -1397,7 +1407,7 @@
<subsection name="SSL Support - Connector - NIO and NIO2 (deprecated)">
<p>The following NIO and NIO2 SSL configuration attributes have been
- deprecated in favour of the default
+ deprecated in favor of the default
<a href="#SSL_Support_-_SSLHostConfig">SSLHostConfig</a> element.
</p>
@@ -1715,8 +1725,8 @@
</tr>
<tr>
<th style="text-align: left;">SSL Support</th>
- <td>Java SSL</td>
- <td>Java SSL</td>
+ <td>Java SSL or OpenSSL</td>
+ <td>Java SSL or OpenSSL</td>
<td>OpenSSL</td>
</tr>
<tr>
Modified: tomcat/trunk/webapps/docs/ssl-howto.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/ssl-howto.xml?rev=1729644&r1=1729643&r2=1729644&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/ssl-howto.xml (original)
+++ tomcat/trunk/webapps/docs/ssl-howto.xml Wed Feb 10 16:31:51 2016
@@ -269,11 +269,12 @@ Certificate that can be used by your ser
<subsection name="Edit the Tomcat Configuration File">
<p>
-Tomcat can use two different implementations of SSL:
+Tomcat can use three different implementations of SSL:
</p>
<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>
+<li>JSSE implementation provided as part of the Java runtime</li>
+<li>JSSE implementation that uses OpenSSL</li>
+<li>APR implementation, which uses the OpenSSL engine by default</li>
</ul>
<p>
The exact configuration details depend on which implementation is being used.
@@ -281,29 +282,30 @@ If you configured Connector by specifyin
<code>protocol="HTTP/1.1"</code> then the implementation used by Tomcat is
chosen automatically. 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
+then it will use the JSSE OpenSSL implementation, otherwise it will use the
Java
JSSE implementation.
</p>
<p>
-As configuration attributes for SSL support significantly differ between
-APR vs. JSSE implementations, it is <strong>recommended</strong> to
-avoid auto-selection of implementation. It is done by specifying a classname
+Auto-selection of implementation can be avoided if needed. It is done by
specifying a classname
in the <b>protocol</b> attribute of the <a
href="config/http.html">Connector</a>.</p>
<p>To define a Java (JSSE) connector, regardless of whether the APR library is
loaded or not, use one of the following:</p>
<source><![CDATA[<!-- Define a HTTP/1.1 Connector on port 8443, JSSE NIO
implementation -->
<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
+
sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation"
port="8443" .../>
<!-- Define a HTTP/1.1 Connector on port 8443, JSSE NIO2 implementation -->
<Connector protocol="org.apache.coyote.http11.Http11Nio2Protocol"
+
sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation"
port="8443" .../>]]></source>
-<p>Tomcat also provides a SSL engine that directly uses OpenSSL. If the APR
library
+<p>The OpenSSL JSSE implementation can also be configured explicitly if
needed. If the APR library
is installed (as for using the APR connector), using the sslImplementationName
attribute
-allows enabling it. In that case, the configuration can use either the JSSE
attributes or
+allows enabling it. When using the OpenSSL JSSE implementation, the
configuration can use
+either the JSSE attributes or
the OpenSSL attributes (as used for the APR connector), but must not mix
attributes from
both types in the same SSLHostConfig or Connector element.</p>
<source><![CDATA[<!-- Define a HTTP/1.1 Connector on port 8443, JSSE NIO
implementation and OpenSSL -->
@@ -316,15 +318,20 @@ both types in the same SSLHostConfig or
<Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
port="8443" .../>]]></source>
-<p>If you are using APR, you have the option of configuring an alternative
engine to OpenSSL.</p>
+<p>If you are using APR or JSSE OpenSSL, you have the option of configuring an
alternative engine to OpenSSL.</p>
<source><![CDATA[<Listener
className="org.apache.catalina.core.AprLifecycleListener"
SSLEngine="someengine" SSLRandomSeed="somedevice" />]]></source>
<p>The default value is</p>
<source><![CDATA[<Listener
className="org.apache.catalina.core.AprLifecycleListener"
SSLEngine="on" SSLRandomSeed="builtin" />]]></source>
+<p>Also the <code>useAprConnector</code> attribute may be used to have Tomcat
default to
+using the APR connector rather than the NIO connector:</p>
+<source><![CDATA[<Listener
className="org.apache.catalina.core.AprLifecycleListener"
+ useAprConnector="true" SSLEngine="on" SSLRandomSeed="builtin"
/>]]></source>
<p>
-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.
+So to enable OpenSSL, 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 OpenSSL engine name.
</p>
<p>
@@ -338,7 +345,7 @@ sources like "/dev/urandom" that will al
<code>$CATALINA_BASE</code> represents the base directory for the
Tomcat instance. An example <code><Connector></code> element
for an SSL connector is included in the default <code>server.xml</code>
-file installed with Tomcat. To configure an SSL connector that uses JSSE, you
+file installed with Tomcat. To configure an SSL connector that uses JSSE, you
will need to remove the comments and edit it so it looks something like
this:</p>
<source><![CDATA[<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
@@ -349,6 +356,10 @@ this:</p>
keystoreFile="${user.home}/.keystore" keystorePass="changeit"
clientAuth="false" sslProtocol="TLS"/>]]></source>
<p>
+ Note: If tomcat-native is installed, the configuration will use JSSE with
+ an OpenSSL implementation, which supports either this configuration or the
APR
+ configuration example given below.</p>
+<p>
The APR connector uses different attributes for many SSL settings,
particularly keys and certificates. An example of an APR configuration
is:</p>
<source><