You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by re...@apache.org on 2016/02/10 17:31:52 UTC
svn commit: r1729644 - in /tomcat/trunk/webapps/docs: apr.xml
config/http.xml ssl-howto.xml
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><![CDATA[<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
@@ -365,8 +376,9 @@ this:</p>
are mandatory, are documented in the SSL Support section of the
<a href="config/http.html#SSL_Support">HTTP connector</a> configuration
reference. Make sure that you use the correct attributes for the connector you
-are using. The NIO and NIO2 connectors use JSSE whereas the APR/native connector
-uses APR.</p>
+are using. The NIO and NIO2 connectors use JSSE unless the JSSE OpenSSL implementation is
+installed (in which case it supports either the JSSE or OpenSSL configuration styles),
+whereas the APR/native connector uses APR.</p>
<p>The <code>port</code> attribute is the TCP/IP
port number on which Tomcat will listen for secure connections. You can
@@ -500,7 +512,7 @@ SSL communications, and what to do about
"java.security.InvalidAlgorithmParameterException: Prime size must be multiple
of 64, and can only range from 512 to 1024 (inclusive)"
- <p>If you are using the APR/native connector,
+ <p>If you are using the APR/native connector or the JSSE OpenSSL implementation,
it will determine the strength of ephemeral DH keys from the key size of
your RSA certificate. For example a 2048 bit RSA key will result in
using a 2048 bit prime for the DH keys. Unfortunately Java 6 only supports
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org