This is an automated email from the ASF dual-hosted git repository.
remm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/main by this push:
new ebead09534 OpenSSL documentation update
ebead09534 is described below
commit ebead095344526635e4c7a946235b2efddc1736a
Author: remm <r...@apache.org>
AuthorDate: Fri Dec 22 10:53:54 2023 +0100
OpenSSL documentation update
---
webapps/docs/config/http.xml | 7 +++++++
webapps/docs/config/listeners.xml | 19 +++++++++++++------
webapps/docs/ssl-howto.xml | 36 ++++++++++++++++++++----------------
3 files changed, 40 insertions(+), 22 deletions(-)
diff --git a/webapps/docs/config/http.xml b/webapps/docs/config/http.xml
index 31f273f615..e425bd7359 100644
--- a/webapps/docs/config/http.xml
+++ b/webapps/docs/config/http.xml
@@ -1565,6 +1565,10 @@
implementation depending on the processor being used,
and can be complemented with many commercial accelerator components.</p>
+ <p>When OpenSSL FFM support is enabled, the connectors will default to using
+ OpenSSL through JSSE, which is equivalent but uses the Java FFM API from
+ Java 22 to access OpenSSL.</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>
@@ -1594,6 +1598,9 @@
will automatically enable it and the default value of this attribute
becomes
<code>org.apache.tomcat.util.net.openssl.OpenSSLImplementation</code>.
+ The FFM API from Java 22 may also be used to enable OpenSSL support, in
+ which case the default value of the attribute becomes
+
<code>org.apache.tomcat.util.net.openssl.panama.OpenSSLImplementation</code>.
In that case, the attributes from either JSSE and OpenSSL
configuration styles can be used, as long as the two types are not mixed
(for example, it is not allowed to define use of a Java keystore and
diff --git a/webapps/docs/config/listeners.xml
b/webapps/docs/config/listeners.xml
index df2999e7bd..c58f45ea9f 100644
--- a/webapps/docs/config/listeners.xml
+++ b/webapps/docs/config/listeners.xml
@@ -83,8 +83,8 @@
<subsection name="APR Lifecycle Listener -
org.apache.catalina.core.AprLifecycleListener">
<p>The <strong>APR Lifecycle Listener</strong> checks for the presence of
- the APR/native library and loads the library if it is present. For more
- information see the <a href="../apr.html">APR/native guide</a>.</p>
+ the Apache Tomcat Native library and loads the library if it is present.
+ For more information see the <a href="../apr.html">APR/native
guide</a>.</p>
<p>This listener must only be nested within <a
href="server.html">Server</a>
elements.</p>
@@ -299,14 +299,15 @@
<p>The <strong>OpenSSL Lifecycle Listener</strong> checks for the presence
of the OpenSSL library and loads the library if it is present. This
- uses the FFM API and requires Java 22 or newer. When enabled and
- successfully loaded, NIO and NIO2 connector will then make use of OpenSSL
- for TLS functionality.</p>
+ uses the FFM API from Java 22 instead of additional native code. When
+ enabled and successfully loaded, NIO and NIO2 connector will then make use
+ of OpenSSL for TLS functionality. This is a functional replacement to the
+ <strong>APR Lifecycle Listener</strong> described above.</p>
<p>This listener must only be nested within <a
href="server.html">Server</a>
elements.</p>
- <p>The following additional attributes are supported by the <strong>APR
+ <p>The following additional attributes are supported by the <strong>OpenSSL
Lifecycle Listener</strong>:</p>
<attributes>
@@ -345,6 +346,12 @@
<p>The default value is <code>off</code>.</p>
</attribute>
+ <attribute name="useOpenSSL" required="false">
+ <p>This attribute controls the auto-selection of the OpenSSL JSSE
+ implementation. The default is <code>true</code> which will use OpenSSL
+ if the FFM API is available.</p>
+ </attribute>
+
</attributes>
</subsection>
diff --git a/webapps/docs/ssl-howto.xml b/webapps/docs/ssl-howto.xml
index bf04446e2f..0f754a1f72 100644
--- a/webapps/docs/ssl-howto.xml
+++ b/webapps/docs/ssl-howto.xml
@@ -262,10 +262,7 @@ Tomcat can use two different implementations of SSL:
The exact configuration details depend on which implementation is being used.
If you configured Connector by specifying generic
<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 JSSE OpenSSL implementation, otherwise it will use the
Java
-JSSE implementation.
+chosen automatically.
</p>
<p>
@@ -285,22 +282,29 @@ loaded or not, use one of the following:</p>
port="8443" .../>]]></source>
<p>The OpenSSL JSSE implementation can also be configured explicitly if needed.
-If the APR library is installed, using the sslImplementationName attribute
-allows enabling it. When using the OpenSSL JSSE implementation, the
+If the Tomcat Native library or Java 22 is installed, using the
sslImplementationName
+attribute allows enabling it. When using the OpenSSL JSSE implementation, the
configuration can use either the JSSE attributes or the OpenSSL attributes, but
must not mix attributes from both types in the same SSLHostConfig or Connector
element.</p>
+<p>With Tomcat Native:</p>
<source><![CDATA[<!-- Define an HTTP/1.1 Connector on port 8443, JSSE NIO
implementation and OpenSSL -->
<Connector protocol="org.apache.coyote.http11.Http11NioProtocol" port="8443"
sslImplementationName="org.apache.tomcat.util.net.openssl.OpenSSLImplementation"
.../>]]></source>
+<p>With Java 22 FFM API:</p>
+<source><![CDATA[<!-- Define an HTTP/1.1 Connector on port 8443, JSSE NIO
implementation and OpenSSL -->
+<Connector protocol="org.apache.coyote.http11.Http11NioProtocol" port="8443"
+
sslImplementationName="org.apache.tomcat.util.net.openssl.panama.OpenSSLImplementation"
+ .../>]]></source>
<p>If you are using JSSE OpenSSL, you have the option of configuring an
alternative engine to OpenSSL.</p>
+<p>With Tomcat Native:</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>With Java 22 FFM API:</p>
+<source><![CDATA[<Listener
className="org.apache.catalina.core.OpenSSLLifecycleListener"
+ SSLEngine="someengine" SSLRandomSeed="somedevice" />]]></source>
<p>
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,
@@ -454,17 +458,17 @@ mailing list</a>.</p>
</section>
<section name="Using OCSP Certificates">
-<p>To use Online Certificate Status Protocol (OCSP) with Apache Tomcat, ensure
- you have downloaded, installed, and configured the
- <a href="https://tomcat.apache.org/download-native.cgi";>
- Tomcat Native Connector</a>.
-Furthermore, if you use the Windows platform, ensure you download the
-ocsp-enabled connector.</p>
+ <p>
+ Support of the Online Certificate Status Protocol (OCSP) in Apache
Tomcat
+ uses OpenSSL. This can be used either through
+ <a href="https://tomcat.apache.org/download-native.cgi";>Tomcat
Native</a>
+ or the FFM API on Java 22 and newer.
+ </p>
<p>To use OCSP, you require the following:</p>
<ul>
<li>OCSP-enabled certificates</li>
- <li>Tomcat with SSL APR connector</li>
+ <li>Tomcat with an OpenSSL enabled connector</li>
<li>Configured OCSP responder</li>
</ul>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
