Summary

Add a new constructor to com.sun.net.httpserver.BasicAuthenticator to support specifying a character set to use when decoding usernames and passwords supplied by HTTP clients.

Problem

The original specification for HTTP Basic authentication did not specify the character set to use when converting usernames and passwords to bytes to be sent with HTTP requests. Therefore, the character set used varies in practice. The JDK HTTP server implementation currently uses the platform's default character set. We need a more precise/flexible mechanism than this.

Solution

Add the proposed constructor to com.sun.net.httpserver.BasicAuthenticator which allows the character set to be specified. In the special case where UTF-8 is specified (the recommended value) the implementation can make use of the mechanism defined in RFC7617 to communicate the proposed character set to the client (though this is not part of the specification). As part of this enhancement, the two HTTP clients in the JDK (java.net.HttpURLConnection and java.net.http.HttpClient) will both obey the RFC7617 charset mechanism.

Specification

Change doc to existing constructor and add new constructor as below:

     /**
-     * Creates a BasicAuthenticator for the given HTTP realm
+     * Creates a BasicAuthenticator for the given HTTP realm.
+     * The Basic authentication credentials (username and password) are decoded
+     * using the platform's {@link Charset#defaultCharset() default character set}.
+     *
      * @param realm The HTTP Basic authentication realm
-     * @throws NullPointerException if the realm is an empty string
+     * @throws NullPointerException if realm is {@code null}
+     * @throws IllegalArgumentException if realm is an empty string
      */
     public BasicAuthenticator (String realm) {..}
+
+    /**
+     * Creates a BasicAuthenticator for the given HTTP realm and using the
+     * given {@link Charset} to decode the Basic authentication credentials
+     * (username and password).
+     *
+     * @apiNote {@code UTF-8} is the recommended charset because its usage is
+     * communicated to the client, and therefore more likely to be used also
+     * by the client.
+     *
+     * @param realm The HTTP Basic authentication realm
+     * @param charset The Charset to decode incoming credentials from the client
+     * @throws NullPointerException if realm or charset are {@code null}
+     * @throws IllegalArgumentException if realm is an empty string
+     */
+    public BasicAuthenticator (String realm, Charset charset) {..}