(tomcat) 04/16: Use UTF-8 for WebSocket client basic authentication credentials

[re...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

rmaucher pushed a commit to branch 11.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git

commit 3f63ef97926ab637a6d3b50d99c81af74d2a7606
Author: opencode <re...@apache.org>
AuthorDate: Fri Oct 16 23:21:41 2026 +0200

    Use UTF-8 for WebSocket client basic authentication credentials
    
    The WebSocket client's BasicAuthenticator only selected UTF-8 when the
    server challenge carried a charset parameter with the value UTF-8 (case
    insensitively) and silently fell back to ISO-8859-1 for any other
    value, including values that RFC 7617 section 2.1 does not allow at
    all. Credentials containing characters outside ISO-8859-1 were then
    silently corrupted to '?' by the ISO-8859-1 encoding, resulting in
    mysterious authentication failures against such servers.
    
    RFC 7617 section 2.1 leaves the default encoding undefined (provided it
    is ASCII compatible) and allows only UTF-8 as the value of the charset
    parameter, reserving other values for future use. Encode the
    credentials with UTF-8 by default and reject challenges asking for any
    other encoding rather than silently guessing one. Add a unit test that
    checks the encoding byte-wise and the rejection of disallowed values.
    
    Found by code review.
---
 .../tomcat/websocket/BasicAuthenticator.java       | 20 ++++--
 .../tomcat/websocket/LocalStrings.properties       |  2 +
 .../tomcat/websocket/TestBasicAuthenticator.java   | 82 ++++++++++++++++++++++
 webapps/docs/changelog.xml                         |  6 ++
 4 files changed, 103 insertions(+), 7 deletions(-)

diff --git a/java/org/apache/tomcat/websocket/BasicAuthenticator.java b/java/org/apache/tomcat/websocket/BasicAuthenticator.java
index 266c2e3c67..649457bac0 100644
--- a/java/org/apache/tomcat/websocket/BasicAuthenticator.java
+++ b/java/org/apache/tomcat/websocket/BasicAuthenticator.java
@@ -16,16 +16,19 @@
  */
 package org.apache.tomcat.websocket;
 
-import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
 import java.util.Base64;
 import java.util.Map;
 
+import org.apache.tomcat.util.res.StringManager;
+
 /**
  * Authenticator supporting the BASIC authentication method.
  */
 public class BasicAuthenticator extends Authenticator {
 
+    private static final StringManager sm = StringManager.getManager(BasicAuthenticator.class);
+
     /** Default constructor. */
     public BasicAuthenticator() { }
 
@@ -47,15 +50,18 @@ public class BasicAuthenticator extends Authenticator {
         validateRealm(userRealm, realm);
 
         String userPass = userName + ":" + userPassword;
-        Charset charset;
 
-        if (parameterMap.get(charsetparam) != null && parameterMap.get(charsetparam).equalsIgnoreCase("UTF-8")) {
-            charset = StandardCharsets.UTF_8;
-        } else {
-            charset = StandardCharsets.ISO_8859_1;
+        /*
+         * RFC 7617 section 2.1 leaves the default character encoding undefined and only allows UTF-8 as the value of
+         * the charset parameter, reserving any other value for future use. Use UTF-8 by default and reject challenges
+         * that ask for any other encoding rather than silently guessing one.
+         */
+        String charsetParam = parameterMap.get(charsetparam);
+        if (charsetParam != null && !charsetParam.equalsIgnoreCase("UTF-8")) {
+            throw new AuthenticationException(sm.getString("basicAuthenticator.invalidCharset", charsetParam));
         }
 
-        String base64 = Base64.getEncoder().encodeToString(userPass.getBytes(charset));
+        String base64 = Base64.getEncoder().encodeToString(userPass.getBytes(StandardCharsets.UTF_8));
 
         return " Basic " + base64;
     }
diff --git a/java/org/apache/tomcat/websocket/LocalStrings.properties b/java/org/apache/tomcat/websocket/LocalStrings.properties
index 185bc2f7fc..0409deced5 100644
--- a/java/org/apache/tomcat/websocket/LocalStrings.properties
+++ b/java/org/apache/tomcat/websocket/LocalStrings.properties
@@ -38,6 +38,8 @@ authenticator.realmMismatch=The user provided authentication realm [{0}] did not
 
 backgroundProcessManager.processFailed=A background process failed
 
+basicAuthenticator.invalidCharset=The value [{0}] of the charset parameter in the authentication challenge is not permitted. The only permitted value is UTF-8
+
 caseInsensitiveKeyMap.nullKey=Null keys are not permitted
 
 clientEndpointHolder.instanceCreationFailed=Failed to create WebSocketEndpoint
diff --git a/test/org/apache/tomcat/websocket/TestBasicAuthenticator.java b/test/org/apache/tomcat/websocket/TestBasicAuthenticator.java
new file mode 100644
index 0000000000..62220ef891
--- /dev/null
+++ b/test/org/apache/tomcat/websocket/TestBasicAuthenticator.java
@@ -0,0 +1,82 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.tomcat.websocket;
+
+import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
+import java.util.Base64;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+public class TestBasicAuthenticator {
+
+    @Test
+    public void testAuthorizationNoCharset() throws Exception {
+        // UTF-8 is used by default if no charset is specified. The pound
+        // sign is a single byte in ISO-8859-1 and two bytes in UTF-8 so the
+        // two encodings can be distinguished.
+        String authorization = getAuthorization("Basic realm=\"realm\"", "user", "pass\u00A3word");
+        Assert.assertEquals(" Basic " + encode("user:pass\u00A3word", StandardCharsets.UTF_8), authorization);
+    }
+
+    @Test
+    public void testAuthorizationCharsetUtf8() throws Exception {
+        String authorization = getAuthorization("Basic realm=\"realm\", charset=UTF-8");
+        Assert.assertEquals(" Basic " + encode("user:password", StandardCharsets.UTF_8), authorization);
+    }
+
+    @Test
+    public void testAuthorizationCharsetUtf8NonLatin1() throws Exception {
+        // The UTF-8 bytes of characters that are not present in ISO-8859-1
+        // must be used rather than ISO-8859-1's '?' replacements
+        String authorization = getAuthorization("Basic realm=\"realm\", charset=UTF-8", "user", "\u7528\u6237");
+        Assert.assertEquals(" Basic " + encode("user:\u7528\u6237", StandardCharsets.UTF_8), authorization);
+    }
+
+    @Test
+    public void testAuthorizationCharsetUtf8LowerCase() throws Exception {
+        String authorization = getAuthorization("Basic realm=\"realm\", charset=utf-8");
+        Assert.assertEquals(" Basic " + encode("user:password", StandardCharsets.UTF_8), authorization);
+    }
+
+    @Test(expected = AuthenticationException.class)
+    public void testAuthorizationCharsetIso88592() throws Exception {
+        // RFC 7617 section 2.1: UTF-8 is the only permitted value
+        getAuthorization("Basic realm=\"realm\", charset=ISO-8859-2");
+    }
+
+    @Test(expected = AuthenticationException.class)
+    public void testAuthorizationCharsetInvalid() throws Exception {
+        // RFC 7617 section 2.1: UTF-8 is the only permitted value
+        getAuthorization("Basic realm=\"realm\", charset=garbage");
+    }
+
+    private static String getAuthorization(String authenticateHeader) throws AuthenticationException {
+        return getAuthorization(authenticateHeader, "user", "password");
+    }
+
+    private static String getAuthorization(String authenticateHeader, String userName, String userPassword)
+            throws AuthenticationException {
+        BasicAuthenticator authenticator = new BasicAuthenticator();
+        return authenticator.getAuthorization("GET", "/ws/echo", authenticateHeader, userName, userPassword, null);
+    }
+
+    private static String encode(String value, Charset charset) {
+        return Base64.getEncoder().encodeToString(value.getBytes(charset));
+    }
+}
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index 3f857f6245..b3719e5262 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -415,6 +415,12 @@
         The hash of the (empty) entity body was omitted, resulting in an
         incorrect response that the server always rejected. (remm)
       </fix>
+      <fix>
+        Encode the credentials used for basic authentication by the WebSocket
+        client with UTF-8 by default rather than ISO-8859-1, and reject
+        challenges that specify a charset other than UTF-8, the only value
+        RFC 7617 allows. (remm)
+      </fix>
     </changelog>
   </subsection>
   <subsection name="Web applications">


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org