(D)TLS key exchange named groups

Summary

Add new APIs to support key exchange named groups customization for individual (D)TLS connection.

Problem

In a (D)TLS connection, the client and server may support different parameters for key exchange algorithms. These parameters are defined with named groups in (D)TLS specifications (see RFC 8446 and RFC 5246). (D)TLS specifications define the procedure to negotiate the named group that could be used in key exchanging during the negotiation of (D)TLS connections.

JDK implements the procedure to negotiate with essential key exchange named groups. Applications could configure the JDK default named groups. Rather than using the provider default named groups, applications may want to customize the named groups 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 key exchange named groups for individual connections.

Specification

1. Add a get method to access the key exchange named groups customization in the javax.net.ssl.SSLParameters class.

   +    /**
   +     * Returns a prioritized array of key exchange named groups names that
   +     * can be used over the SSL/TLS/DTLS protocols.
   +     * <p>
   +     * Note that the standard list of key exchange named groups are defined
   +     * in the <a href=
   +     * "{@docRoot}/../specs/security/standard-names.html#named-groups">
   +     * Named Groups</a> section of the Java Security Standard Algorithm
   +     * Names Specification.  Providers may support named groups not defined
   +     * in this list or may not use the recommended name for a certain named
   +     * group.
   +     * <p>
   +     * The set of named groups 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 named groups.
   +     * <p>
   +     * If the returned array is {@code null}, then the underlying
   +     * provider-specific default named groups will be used over the
   +     * SSL/TLS/DTLS connections.
   +     * <p>
   +     * If the returned array is empty (zero-length), then the named group
   +     * 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
   +     * name groups.
   +     * <p>
   +     * If the returned array is not {@code null} or empty (zero-length),
   +     * then the named groups in the returned array will be used over
   +     * the SSL/TLS/DTLS connections.  This parameter will override the
   +     * underlying provider-specific default named groups.
   +     * <p>
   +     * This method returns the most recent value passed to
   +     * {@link #setNamedGroups} if that method has been called and otherwise
   +     * returns the default named groups 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
   +     * named groups for connection populated objects.
   +     *
   +     * @implNote
   +     * The SunJSSE provider supports this method.
   +     *
   +     * @implNote
   +     * Note that applications may use the
   +     * {@systemProperty jdk.tls.namedGroups} system property with the SunJSSE
   +     * provider to override the provider-specific default named groups.
   +     *
   +     * @return an array of key exchange named group names {@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 named group preference, with the first
   +     *         entry being the most preferred.  Providers should ignore unknown
   +     *         named group names while establishing the SSL/TLS/DTLS
   +     *         connections.
   +     * @see #setNamedGroups
   +     *
   +     * @since 20
   +     */
   +    public String[] getNamedGroups();

2. Add a set method to customize the key exchange named groups in the javax.net.ssl.SSLParameters class.

   +    /**
   +     * Sets the prioritized array of key exchange named groups names that
   +     * can be used over the SSL/TLS/DTLS protocols.
   +     * <p>
   +     * Note that the standard list of key exchange named groups are defined in
   +     * the <a href=
   +     * "{@docRoot}/../specs/security/standard-names.html#named-groups">
   +     * Named Groups</a> section of the Java Security Standard Algorithm
   +     * Names Specification.  Providers may support named groups not defined
   +     * in this list or may not use the recommended name for a certain named
   +     * group.
   +     * <p>
   +     * The set of named groups that will be used over the SSL/TLS/DTLS
   +     * connections is determined by the input parameter {@code namedGroups}
   +     * array and the underlying provider-specific default named groups.
   +     * See {@link #getNamedGroups} 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 named groups that are set.
   +     *
   +     * @implNote
   +     * The SunJSSE provider supports this method.
   +     *
   +     * @param namedGroups an ordered array of key exchange named group 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 named group scheme names while establishing the
   +     *        SSL/TLS/DTLS connections.
   +     * @throws IllegalArgumentException if any element in the
   +     *        {@code namedGroups} array is a duplicate, {@code null} or
   +     *        {@linkplain String#isBlank() blank}.
   +     *
   +     * @see #getNamedGroups
   +     *
   +     * @since 20
   +     */
   +    public void setNamedGroups(String[] namedGroups) {

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