Add support for setting TLS 1.3 cipher suites

For consistency between OpenSSL and JSSE TLS implementations, TLSv.13 cipher
suites included in the ciphers attribute of an SSLHostConfig are now always
ignored (previously they would be ignored with OpenSSL implementations and
used with JSSE implementations) and a warning is logged that the cipher suite
has been ignored.

Author: markt-asf

java/org/apache/tomcat/util/net/LocalStrings.properties

@@ -147,6 +147,8 @@ socketWrapper.writeTimeout=Write timeout
 sslHostConfig.certificate.notype=Multiple certificates were specified and at least one is missing the required attribute type
 sslHostConfig.certificateVerificationInvalid=The certificate verification value [{0}] is not recognised
 sslHostConfig.fileNotFound=Configured file [{0}] does not exist
+sslHostConfig.ignoreNonTls13Ciphersuite=The non-TLS 1.3 cipher suite [{0}] included in the TLS 1.3 cipher suite list will be ignored
+sslHostConfig.ignoreTls13Ciphersuite=The TLS 1.3 cipher suite [{0}] included in the TLS 1.2 and below ciphers list will be ignored
 sslHostConfig.invalid_truststore_password=The provided trust store password could not be used to unlock and/or validate the trust store. Retrying to access the trust store with a null password which will skip validation.
 sslHostConfig.mismatch=The property [{0}] was set on the SSLHostConfig named [{1}] and is for the [{2}] configuration syntax but the SSLHostConfig is being used with the [{3}] configuration syntax
 sslHostConfig.mismatch.trust=The trust configuration property [{0}] was set on the SSLHostConfig named [{1}] and is for the [{2}] configuration syntax but the SSLHostConfig is being used with the [{3}] trust configuration syntax

java/org/apache/tomcat/util/net/SSLHostConfig.java

@@ -111,8 +111,10 @@ public class SSLHostConfig implements Serializable {
     private int certificateVerificationDepth = 10;
     // Used to track if certificateVerificationDepth has been explicitly set
     private boolean certificateVerificationDepthConfigured = false;
-    private String ciphers = DEFAULT_TLS_CIPHERS;
+    private String ciphers = DEFAULT_TLS_CIPHERS_12;
+    private String cipherSuites = DEFAULT_TLS_CIPHERS_13;
     private LinkedHashSet<Cipher> cipherList = null;
+    private LinkedHashSet<Cipher> cipherSuiteList = null;
     private List<String> jsseCipherNames = null;
     private boolean honorCipherOrder = false;
     private final Set<String> protocols = new HashSet<>();
@@ -383,36 +385,59 @@ public boolean isCertificateVerificationDepthConfigured() {
 
 
     /**
-     * Set the new cipher configuration. Note: Regardless of the format used to set the configuration, it is always
-     * stored in OpenSSL format.
+     * Set the new cipher (TLSv1.2 and below) configuration. Note: Regardless of the format used to set the
+     * configuration, it is always stored in OpenSSL format.
      *
      * @param ciphersList The new cipher configuration in OpenSSL or JSSE format
      */
     public void setCiphers(String ciphersList) {
         // Ciphers is stored in OpenSSL format. Convert the provided value if
         // necessary.
-        if (ciphersList != null && !ciphersList.contains(":")) {
-            StringBuilder sb = new StringBuilder();
-            // Not obviously in OpenSSL format. Might be a single OpenSSL or JSSE
-            // cipher name. Might be a comma separated list of cipher names
-            String[] ciphers = ciphersList.split(",");
-            for (String cipher : ciphers) {
-                String trimmed = cipher.trim();
-                if (!trimmed.isEmpty()) {
-                    String openSSLName = OpenSSLCipherConfigurationParser.jsseToOpenSSL(trimmed);
-                    if (openSSLName == null) {
-                        // Not a JSSE name. Maybe an OpenSSL name or alias
-                        openSSLName = trimmed;
+        if (ciphersList != null) {
+            if (ciphersList.contains(":")) {
+                // OpenSSL format
+                StringBuilder sb = new StringBuilder();
+                String[] components = ciphersList.split(":");
+                // Remove any TLS 1.3 cipher suites
+                for (String component : components) {
+                    String trimmed = component.trim();
+                    if (OpenSSLCipherConfigurationParser.isTls13Cipher(trimmed)) {
+                        log.warn(sm.getString("sslHostConfig.ignoreTls13Ciphersuite", trimmed));
+                    } else {
+                        if (!sb.isEmpty()) {
+                            sb.append(':');
+                        }
+                        sb.append(trimmed);
                     }
-                    if (!sb.isEmpty()) {
-                        sb.append(':');
+                }
+                this.ciphers = sb.toString();
+            } else {
+                // Not obviously in OpenSSL format. Might be a single OpenSSL or JSSE
+                // cipher name. Might be a comma separated list of cipher names
+                StringBuilder sb = new StringBuilder();
+                String[] ciphers = ciphersList.split(",");
+                for (String cipher : ciphers) {
+                    String trimmed = cipher.trim();
+                    if (!trimmed.isEmpty()) {
+                        if (OpenSSLCipherConfigurationParser.isTls13Cipher(trimmed)) {
+                            log.warn(sm.getString("sslHostConfig.ignoreTls13Ciphersuite", trimmed));
+                            continue;
+                        }
+                        String openSSLName = OpenSSLCipherConfigurationParser.jsseToOpenSSL(trimmed);
+                        if (openSSLName == null) {
+                            // Not a JSSE name. Maybe an OpenSSL name or alias
+                            openSSLName = trimmed;
+                        }
+                        if (!sb.isEmpty()) {
+                            sb.append(':');
+                        }
+                        sb.append(openSSLName);
                     }
-                    sb.append(openSSLName);
                 }
+                this.ciphers = sb.toString();
             }
-            this.ciphers = sb.toString();
         } else {
-            this.ciphers = ciphersList;
+            this.ciphers = null;
         }
         this.cipherList = null;
         this.jsseCipherNames = null;
@@ -443,12 +468,76 @@ public LinkedHashSet<Cipher> getCipherList() {
      */
     public List<String> getJsseCipherNames() {
         if (jsseCipherNames == null) {
-            jsseCipherNames = OpenSSLCipherConfigurationParser.convertForJSSE(getCipherList());
+            Set<Cipher> jsseCiphers = new HashSet<>();
+            jsseCiphers.addAll(getCipherSuiteList());
+            jsseCiphers.addAll(getCipherList());
+            jsseCipherNames = OpenSSLCipherConfigurationParser.convertForJSSE(jsseCiphers);
         }
         return jsseCipherNames;
     }
 
 
+    /**
+     * Set the cipher suite (TLSv1.3) configuration.
+     *
+     * @param cipherSuites The cipher suites to use in a colon-separated, preference order list
+     */
+    public void setCipherSuites(String cipherSuites) {
+        StringBuilder sb = new StringBuilder();
+        String[] values;
+        if (cipherSuites.contains(":")) {
+            // OpenSSL format
+            values = cipherSuites.split(":");
+        } else {
+            // JSSE format or possible a single cipher suite name
+            values = cipherSuites.split(",");
+        }
+        for (String value : values) {
+            String trimmed = value.trim();
+            if (!trimmed.isEmpty()) {
+                if (!OpenSSLCipherConfigurationParser.isTls13Cipher(trimmed)) {
+                    log.warn(sm.getString("sslHostConfig.ignoreNonTls13Ciphersuite", trimmed));
+                    continue;
+                }
+                /*
+                 * OpenSSL and JSSE names for TLSv1.3 cipher suites are currently (January 2026) the same but handle the
+                 * possible future case where they are not.
+                 */
+                String openSSLName = OpenSSLCipherConfigurationParser.jsseToOpenSSL(trimmed);
+                if (openSSLName == null) {
+                    // Not a JSSE name. Maybe an OpenSSL name or alias
+                    openSSLName = trimmed;
+                }
+                if (!sb.isEmpty()) {
+                    sb.append(':');
+                }
+                sb.append(trimmed);
+            }
+        }
+        this.cipherSuites = sb.toString();
+        this.cipherSuiteList = null;
+        this.jsseCipherNames = null;
+    }
+
+
+    /**
+     * Obtain the current cipher suite (TLSv1.3) configuration.
+     *
+     * @return An OpenSSL cipher suite string for the current configuration.
+     */
+    public String getCipherSuites() {
+        return cipherSuites;
+    }
+
+
+    private LinkedHashSet<Cipher> getCipherSuiteList() {
+        if (cipherSuiteList == null) {
+            cipherSuiteList = OpenSSLCipherConfigurationParser.parse(getCipherSuites());
+        }
+        return cipherSuiteList;
+    }
+
+
     public void setHonorCipherOrder(boolean honorCipherOrder) {
         this.honorCipherOrder = honorCipherOrder;
     }

java/org/apache/tomcat/util/net/openssl/OpenSSLContext.java

@@ -318,6 +318,7 @@ public void init(KeyManager[] kms, TrustManager[] tms, SecureRandom sr) throws K
 
             // Configure the ciphers that the client is permitted to negotiate
             SSLContext.setCipherSuite(state.ctx, sslHostConfig.getCiphers());
+            SSLContext.setCipherSuitesEx(state.ctx, sslHostConfig.getCipherSuites());
 
             // If there is no certificate file must be using a KeyStore so a KeyManager is required.
             // If there is a certificate file a KeyManager is helpful but not strictly necessary.

java/org/apache/tomcat/util/net/openssl/panama/OpenSSLContext.java

@@ -515,14 +515,14 @@ public void init(KeyManager[] kms, TrustManager[] tms, SecureRandom sr) throws K
             }
             if (maxTlsVersion >= TLS1_3_VERSION()) {
                 try {
-                    if (SSL_CTX_set_ciphersuites(state.sslCtx, localArena.allocateFrom(sslHostConfig.getCiphers())) <= 0) {
-                        tls13Warning = sm.getString("engine.failedCipherSuite", sslHostConfig.getCiphers());
+                    if (SSL_CTX_set_ciphersuites(state.sslCtx, localArena.allocateFrom(sslHostConfig.getCipherSuites())) <= 0) {
+                        tls13Warning = sm.getString("engine.failedCipherSuite", sslHostConfig.getCipherSuites());
                     } else {
                         ciphersSet = true;
                     }
                 } catch (NoClassDefFoundError | UnsatisfiedLinkError e) {
                     // Ignore unavailable TLS 1.3 call, which might be compiled out sometimes on LibreSSL
-                    tls13Warning = sm.getString("engine.failedCipherSuite", sslHostConfig.getCiphers());
+                    tls13Warning = sm.getString("engine.failedCipherSuite", sslHostConfig.getCipherSuites());
                 }
             }
             if (!ciphersSet) {

test/org/apache/tomcat/util/net/TestSSLHostConfig.java

@@ -76,6 +76,76 @@ public void testCipher04() {
     }
 
 
+    @Test
+    public void testCipher05() {
+        SSLHostConfig hc = new SSLHostConfig();
+        Cipher c = Cipher.TLS_AES_128_CCM_SHA256;
+
+        // Single TLSv1.3 name - should be filtered out
+        hc.setCiphers(c.getOpenSSLAlias());
+        Assert.assertEquals("", hc.getCiphers());
+    }
+
+
+    @Test
+    public void testCipher06() {
+        SSLHostConfig hc = new SSLHostConfig();
+        Cipher c1 = Cipher.TLS_AES_128_CCM_SHA256;
+        Cipher c2 = Cipher.TLS_RSA_WITH_NULL_MD5;
+
+        // TLSv1.3 then TLSv1.2 - TLSv1.3 name should be filtered out
+        hc.setCiphers(c1.getOpenSSLAlias() + ":" + c2.getOpenSSLAlias());
+        Assert.assertEquals(c2.getOpenSSLAlias(), hc.getCiphers());
+    }
+
+
+    @Test
+    public void testCipher07() {
+        SSLHostConfig hc = new SSLHostConfig();
+        Cipher c1 = Cipher.TLS_AES_128_CCM_SHA256;
+        Cipher c2 = Cipher.TLS_RSA_WITH_NULL_MD5;
+
+        // TLSv1.2 then TLSv1.3 - TLSv1.3 name should be filtered out
+        hc.setCiphers(c2.getOpenSSLAlias() + ":" + c1.getOpenSSLAlias());
+        Assert.assertEquals(c2.getOpenSSLAlias(), hc.getCiphers());
+    }
+
+
+    @Test
+    public void testCiphersuite01() {
+        SSLHostConfig hc = new SSLHostConfig();
+        Cipher c = Cipher.TLS_AES_128_CCM_SHA256;
+
+        // Single TLSv1.3 cipher suite name
+        hc.setCipherSuites(c.getOpenSSLAlias());
+        Assert.assertEquals(c.getOpenSSLAlias(), hc.getCipherSuites());
+    }
+
+
+    @Test
+    public void testCiphersuite02() {
+        SSLHostConfig hc = new SSLHostConfig();
+        Cipher c1 = Cipher.TLS_AES_128_CCM_SHA256;
+        Cipher c2 = Cipher.TLS_RSA_WITH_NULL_MD5;
+
+        // TLSv1.3 then TLSv1.2 - TLSv1.2 name should be filtered out
+        hc.setCipherSuites(c1.getOpenSSLAlias() + ":" + c2.getOpenSSLAlias());
+        Assert.assertEquals(c1.getOpenSSLAlias(), hc.getCipherSuites());
+    }
+
+
+    @Test
+    public void testCiphersuite03() {
+        SSLHostConfig hc = new SSLHostConfig();
+        Cipher c1 = Cipher.TLS_AES_128_CCM_SHA256;
+        Cipher c2 = Cipher.TLS_RSA_WITH_NULL_MD5;
+
+        // TLSv1.2 then TLSv1.3 - TLSv1.2 name should be filtered out
+        hc.setCipherSuites(c2.getOpenSSLAlias() + ":" + c1.getOpenSSLAlias());
+        Assert.assertEquals(c1.getOpenSSLAlias(), hc.getCipherSuites());
+    }
+
+
     @Test
     public void testSerialization() throws IOException, ClassNotFoundException {
         // Dummy OpenSSL command name/value pair