Summary

Add a new method to access more TLS security parameters in both javax.net.ssl.HttpsURLConnection and java.net.SecureCacheResponse.

Problem

For the current HttpsURLConnection and SecureCacheResponse APIs, an application can get the following underlying TLS security parameters:

1. cipher suite in use on this connection,

2. the principal/certificates sent to the HTTPS server during handshaking.

3. the principal/certificates received from the HTTPS server during handshaking.

An application may require to know more TLS security parameters, for example, the negotiated TLS version, the server name indication and the supported signature algorithms. These security parameters are not defined within the current HttpsURLConnection APIs.

Solution

This CSR requests the addition of a new method to access the SSLSession, for both HttpsURLConnection and SecureCacheResponse. More security parameters can be accessed from the SSLSession object associated with the HTTPS connection.

Specification

1. Add a new method to access SSLSession for javax.net.ssl.HttpsURLConnection.

   +    /**
   +     * Returns an {@link Optional} containing the {@code SSLSession} in
   +     * use on this connection.  Returns an empty {@code Optional} if the
   +     * underlying implementation does not support this method.
   +     *
   +     * @implSpec For compatibility, the default implementation of this
   +     *           method returns an empty {@code Optional}.  Subclasses
   +     *           should override this method with an appropriate
   +     *           implementation since an application may need to access
   +     *           additional parameters associated with the SSL session.
   +     *
   +     * @return   an {@link Optional} containing the {@code SSLSession} in
   +     *           use on this connection.
   +     *
   +     * @throws   IllegalStateException if this method is called before
   +     *           the connection has been established
   +     *
   +     * @see SSLSession
   +     *
   +     * @since 12
   +     */
   +    public Optional<SSLSession> getSSLSession() {
   +        return Optional.empty();
   +    }

2. Add a new method to access SSLSession for java.net.SecureCacheResponse.

   +    /**
   +     * Returns an {@link Optional} containing the {@code SSLSession} in
   +     * use on the original connection that retrieved the network resource.
   +     * Returns an empty {@code Optional} if the underlying implementation
   +     * does not support this method.
   +     *
   +     * @implSpec For compatibility, the default implementation of this
   +     *           method returns an empty {@code Optional}.  Subclasses
   +     *           should override this method with an appropriate
   +     *           implementation since an application may need to access
   +     *           additional parameters associated with the SSL session.
   +     *
   +     * @return   an {@link Optional} containing the {@code SSLSession} in
   +     *           use on the original connection
   +     *
   +     * @see SSLSession
   +     *
   +     * @since 12
   +     */
   +    public Optional<SSLSession> getSSLSession() {
   +        return Optional.empty();
   +    }

3. Support the HttpsURLConnection.getSSLSession() operation in the JDK Reference Implementation.

Compatibility Risk

No update to existing behavior, therefore the compatibility impact is minimal.