From 3942be11dcc5d90fdd4f0523a995110084b37af9 Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Thu, 1 Aug 2024 23:49:31 +0200 Subject: [PATCH 1/2] Fixes #12120 - Introduce properties for cipher suites. Added documentation for advanced TLS configuration. Signed-off-by: Simone Bordet --- .../pages/modules/standard.adoc | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/documentation/jetty/modules/operations-guide/pages/modules/standard.adoc b/documentation/jetty/modules/operations-guide/pages/modules/standard.adoc index 0e5c6fef3f8b..5e526b062805 100644 --- 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,57 @@ 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"] +---- + + + + + <1> + <2> + + ^TLS_RSA_.*$ + ^.*_RSA_.*_(MD5|SHA|SHA1)$ + ^.*_DHE_RSA_.*$ + SSL_RSA_WITH_DES_CBC_SHA + SSL_DHE_RSA_WITH_DES_CBC_SHA + SSL_DHE_DSS_WITH_DES_CBC_SHA + SSL_RSA_EXPORT_WITH_RC4_40_MD5 + SSL_RSA_EXPORT_WITH_DES40_CBC_SHA + SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA + SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA + + + + +---- +<1> Reference the existing `sslContextFactory` object. +<2> Call the method `setExcludeCipherSuites(String\...)` to specify the TLS ciphers you want to exclude. + +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 further information. + [[ssl-reload]] == Module `ssl-reload` From 2a52307c994450ae1df2ee7aea6a18e23d92d244 Mon Sep 17 00:00:00 2001 From: Simone Bordet Date: Fri, 2 Aug 2024 11:16:06 +0200 Subject: [PATCH 2/2] Updates after review. Updated the javadoc-url attribute to the new javadocs URI. Signed-off-by: Simone Bordet --- documentation/jetty/antora.yml | 2 +- .../pages/modules/standard.adoc | 25 +++++++++++-------- 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/documentation/jetty/antora.yml b/documentation/jetty/antora.yml index b7eaaad3d603..b6d3bafe1644 100644 --- 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 index 5e526b062805..33a1bad5b521 100644 --- a/documentation/jetty/modules/operations-guide/pages/modules/standard.adoc +++ b/documentation/jetty/modules/operations-guide/pages/modules/standard.adoc @@ -599,28 +599,31 @@ For example, to exclude certain TLS ciphers you can use the following file: <1> + <2> ^TLS_RSA_.*$ - ^.*_RSA_.*_(MD5|SHA|SHA1)$ - ^.*_DHE_RSA_.*$ - SSL_RSA_WITH_DES_CBC_SHA - SSL_DHE_RSA_WITH_DES_CBC_SHA - SSL_DHE_DSS_WITH_DES_CBC_SHA - SSL_RSA_EXPORT_WITH_RC4_40_MD5 - SSL_RSA_EXPORT_WITH_DES40_CBC_SHA - SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA - SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA + ^.*_(MD5|SHA|SHA1)$ + + + + + ^SSL_.*$ + + + ---- <1> Reference the existing `sslContextFactory` object. -<2> Call the method `setExcludeCipherSuites(String\...)` to specify the TLS ciphers you want to exclude. +<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 further information. +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`