Summary

Add new APIs to support signature schemes customization for individual (D)TLS connection.

Problem

In a (D)TLS connection, the client and server may support different signature algorithms. (D)TLS specifications (see RFC 8446 and RFC 5246) define the procedure to negotiate the signature algorithms that could be used in digital signatures during the negotiation of (D)TLS connections.

JDK implemented the procedure and essential signature schemes, and applications could configure the JDK default signature schemes. Rather than using the provider default signature schemes, applications may want to customize the signature schemes for individual connections, for fine control of the security properties. There is no such APIs in Java SE.

Solution

New Java SE public APIs will be defined to customize the signature schemes for individual connections.

Specification

1. Add a get method to access the signature schemes customization in the javax.net.ssl.SSLParameters class.

   +    /**
   +     * Returns a prioritized array of signature scheme names that can be used
   +     * over the SSL/TLS/DTLS protocols.
   +     * <p>
   +     * Note that the standard list of signature scheme names are defined in
   +     * the <a href=
   +     * "{@docRoot}/../specs/security/standard-names.html#signature-schemes">
   +     * Signature Schemes</a> section of the Java Security Standard Algorithm
   +     * Names Specification.  Providers may support signature schemes not
   +     * defined in this list or may not use the recommended name for a certain
   +     * signature scheme.
   +     * <p>
   +     * The set of signature schemes that will be used over the SSL/TLS/DTLS
   +     * connections is determined by the returned array of this method and the
   +     * underlying provider-specific default signature schemes.
   +     * <p>
   +     * If the returned array is {@code null}, then the underlying
   +     * provider-specific default signature schemes will be used over the
   +     * SSL/TLS/DTLS connections.
   +     * <p>
   +     * If the returned array is empty (zero-length), then the signature scheme
   +     * negotiation mechanism is turned off for SSL/TLS/DTLS protocols, and
   +     * the connections may not be able to be established if the negotiation
   +     * mechanism is required by a certain SSL/TLS/DTLS protocol.  This
   +     * parameter will override the underlying provider-specific default
   +     * signature schemes.
   +     * <p>
   +     * If the returned array is not {@code null} or empty (zero-length),
   +     * then the signature schemes in the returned array will be used over
   +     * the SSL/TLS/DTLS connections.  This parameter will override the
   +     * underlying provider-specific default signature schemes.
   +     * <p>
   +     * This method returns the most recent value passed to
   +     * {@link #setSignatureSchemes} if that method has been called and
   +     * otherwise returns the default signature schemes for connection
   +     * populated objects, or {@code null} for pre-populated objects.
   +     *
   +     * @apiNote
   +     * Note that a provider may not have been updated to support this method
   +     * and in that case may return {@code null} instead of the default
   +     * signature schemes for connection populated objects.
   +     *
   +     * @implNote
   +     * The SunJSSE provider supports this method.
   +     *
   +     * @implNote
   +     * Note that applications may use the
   +     * {@systemProperty jdk.tls.client.SignatureSchemes} and/or
   +     * {@systemProperty jdk.tls.server.SignatureSchemes} system properties
   +     * with the SunJSSE provider to override the provider-specific default
   +     * signature schemes.
   +     *
   +     * @return an array of signature scheme {@code Strings} or {@code null} if
   +     *         none have been set.  For non-null returns, this method will
   +     *         return a new array each time it is invoked.  The array is
   +     *         ordered based on signature scheme preference, with the first
   +     *         entry being the most preferred.  Providers should ignore unknown
   +     *         signature scheme names while establishing the SSL/TLS/DTLS
   +     *         connections.
   +     * @see #setSignatureSchemes
   +     *
   +     * @since 19
   +     */
   +    public String[] getSignatureSchemes();

2. Add a set method to customize the signature schemes in the javax.net.ssl.SSLParameters class.

   +    /**
   +     * Sets the prioritized array of signature scheme names that
   +     * can be used over the SSL/TLS/DTLS protocols.
   +     * <p>
   +     * Note that the standard list of signature scheme names are defined in
   +     * the <a href=
   +     * "{@docRoot}/../specs/security/standard-names.html#signature-schemes">
   +     * Signature Schemes</a> section of the Java Security Standard Algorithm
   +     * Names Specification.  Providers may support signature schemes not
   +     *  defined in this list or may not use the recommended name for a certain
   +     * signature scheme.
   +     * <p>
   +     * The set of signature schemes that will be used over the SSL/TLS/DTLS
   +     * connections is determined by the input parameter {@code signatureSchemes}
   +     * array and the underlying provider-specific default signature schemes.
   +     * See {@link #getSignatureSchemes} for specific details on how the
   +     * parameters are used in SSL/TLS/DTLS connections.
   +     *
   +     * @apiNote
   +     * Note that a provider may not have been updated to support this method
   +     * and in that case may ignore the schemes that are set.
   +     *
   +     * @implNote
   +     * The SunJSSE provider supports this method.
   +     *
   +     * @param signatureSchemes an ordered array of signature scheme names with
   +     *        the first entry being the most preferred, or {@code null}.  This
   +     *        method will make a copy of this array.  Providers should ignore
   +     *        unknown signature scheme names while establishing the
   +     *        SSL/TLS/DTLS connections.
   +     * @throws IllegalArgumentException if any element in the
   +     *        {@code signatureSchemes} array is {@code null} or
   +     *        {@linkplain String#isBlank() blank}.
   +     *
   +     * @see #getSignatureSchemes
   +     *
   +     * @since 19
   +     */
   +    public void setSignatureSchemes(String[] signatureSchemes);

3. Added two new terms, connection populated and pre-populated objects, in the javax.net.ssl.SSLParameters class description.

        /**
         * Encapsulates parameters for an SSL/TLS/DTLS connection. The parameters
         * are the list of ciphersuites to be accepted in an SSL/TLS/DTLS handshake,
         * the list of protocols to be allowed, the endpoint identification
         * algorithm during SSL/TLS/DTLS handshaking, the Server Name Indication (SNI),
         * the maximum network packet size, the algorithm constraints, the signature
         * schemes and whether SSL/TLS/DTLS servers should request or require client
         * authentication, etc.
         * <p>
   -     * SSLParameters can be created via the constructors in this class.
   -     * Objects can also be obtained using the {@code getSSLParameters()}
   -     * methods in
   +     * {@code SSLParameter} objects can be created via the constructors in this
   +     * class, and can be described as pre-populated objects. {@code SSLParameter}
   +     * objects can also be obtained using the {@code getSSLParameters()} methods in
         * {@link SSLSocket#getSSLParameters SSLSocket} and
         * {@link SSLServerSocket#getSSLParameters SSLServerSocket} and
         * {@link SSLEngine#getSSLParameters SSLEngine} or the
         * {@link SSLContext#getDefaultSSLParameters getDefaultSSLParameters()} and
         * {@link SSLContext#getSupportedSSLParameters getSupportedSSLParameters()}
   -     * methods in {@code SSLContext}.
   +     * methods in {@code SSLContext}, and can be described as connection populated
   +     * objects.
         * <p>
         * SSLParameters can be applied to a connection via the methods
         * {@link SSLSocket#setSSLParameters SSLSocket.setSSLParameters()} and
         * {@link SSLServerSocket#setSSLParameters SSLServerSocket.setSSLParameters()}
         * and {@link SSLEngine#setSSLParameters SSLEngine.setSSLParameters()}.
         * ...snipped as the sections cannot be displayed properly in the CSR request...
         */
        public class SSLParameters {

4. Support the new added methods in the JDK Reference Implementation.