Fixes #12120 - Introduce properties for cipher suites. (#12126)

Added documentation for advanced TLS configuration. Updated the javadoc-url attribute to the new javadocs URI. Signed-off-by: Simone Bordet <[email protected]>
jetty · Aug 2, 2024 · 84d0574 · 84d0574
1 parent 22a8685
commit 84d0574
Show file tree

Hide file tree

Showing 2 changed files with 59 additions and 1 deletion.
diff --git a/documentation/jetty/antora.yml b/documentation/jetty/antora.yml
@@ -3,7 +3,7 @@ version: '12'
 title: Eclipse Jetty
 asciidoc:
   attributes:
-    javadoc-url: https://jetty.org/javadoc/jetty-12
+    javadoc-url: https://javadoc.jetty.org/jetty-12
     jdurl: '{javadoc-url}'
     jetty-home: ${jetty.home}@
     version: 12.0.10-SNAPSHOT

diff --git a/documentation/jetty/modules/operations-guide/pages/modules/standard.adoc b/documentation/jetty/modules/operations-guide/pages/modules/standard.adoc
@@ -550,6 +550,10 @@ include::{jetty-home}/modules/ssl.mod[tags=documentation-ssl-context]
 [[ssl-keystore-tls]]
 === KeyStore Properties and TLS Properties
 
+The Jetty component that manages the KeyStore, that contains the cryptographic material and the TLS configuration is an instance of `SslContextFactory.Server`.
+
+You can configure the `SslContextFactory.Server` by specifying properties, or by invoking its method for a more xref:ssl-advanced[advanced configuration].
+
 Among the configurable properties, the most relevant are:
 
 `jetty.sslContext.keyStorePath`::
@@ -567,6 +571,60 @@ Whether client certificate authentication should be requested.
 
 If you configure client certificate authentication, you need to configure and distribute a client KeyStore as explained in xref:keystore/index.adoc#client-authn[this section].
 
+[[ssl-advanced]]
+=== Advanced TLS Configuration
+
+Configuring `SslContextFactory.Server` using properties as explained in xref:ssl-keystore-tls[this section] is sufficient for most cases.
+
+For the cases where Jetty module properties are not defined, or when you need more advanced configuration (for example the ability to include and/or exclude the TLS cipher suites), you can follow these steps:
+
+. Modify `$JETTY_BASE/start.d/ssl.ini` by adding a path to a custom XML file, for example:
++
+.ssl.ini
+[source,subs="verbatim,quotes"]
+----
+--module=ssl
+*etc/ssl-config.xml* <1>
+...
+----
+<1> The path to the custom XML file, relative to `$JETTY_BASE`.
+. Create the custom XML file, with your advanced configuration.
+For example, to exclude certain TLS ciphers you can use the following file:
++
+.ssl-config.xml
+[source,xml,subs="verbatim"]
+----
+<?xml version="1.0"?>
+<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://jetty.org/jetty/configure_10_0.dtd">
+
+<Configure>
+  <Ref refid="sslContextFactory"> <1>
+    <!-- Example using the Set element -->
+    <Set name="ExcludeCipherSuites"> <2>
+      <Array type="String">
+        <Item>^TLS_RSA_.*$</Item>
+        <Item>^.*_(MD5|SHA|SHA1)$</Item>
+      </Array>
+    </Set>
+    <!-- Example using the Call element -->
+    <Call name="addExcludeCipherSuites">
+      <Arg>
+        <Array type="String">
+          <Item>^SSL_.*$</Item>
+        </Array>
+      </Arg>
+    </Call>
+  </Ref>
+</Configure>
+----
+<1> Reference the existing `sslContextFactory` object.
+<2> Call the method `setExcludeCipherSuites(String\...)` to specify regular expressions of the TLS ciphers you want to exclude.
+
+The syntax to use in the custom XML file is described in xref:xml/index.adoc[this section].
+
+In the custom XML file you can call any `SslContextFactory.Server` method.
+Refer to the `SslContextFactory.Server` link:{javadoc-url}/org/eclipse/jetty/util/ssl/SslContextFactory.Server.html[javadocs] for the comprehensive list of methods.
+
 [[ssl-reload]]
 == Module `ssl-reload`