OpenSSL documentation update

apache · Dec 22, 2023 · ebead09 · ebead09
1 parent 835173d
commit ebead09
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 22 deletions.
diff --git 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
@@ -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
@@ -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>