Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8051498 JEP 244: TLS Application-Layer Protocol Negotiation Extension
  3. JDK-8062848

Design and Implementation for JEP 244: TLS Application-Layer Protocol Negotiation Extension

    Details

    • Type: Sub-task
    • Status: Resolved
    • Priority: P4
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: security-libs
    • Labels:
      None

      Description

      1. Introduction

      This feature is to support the Application Layer Protocol Negotiation (ALPN) TLS extension as defined in RFC 7301.


      2. Specification

      This section describes the integrated API. (See JDK-8051498 for additional information.)

      ALPN configuration and state are currently handled by the javax.net.ssl.SSLParameters and javax.net.ssl.SSLSocket/javax.net.ssl.SSLEngine JSSE classes. This design defines 6 new public methods for managing application layer protocol names:

       SSLEngine/SSLSocket
      ===================
          /**
           * Returns the most recent application protocol value negotiated for this
           * connection.
           * <p>
           * If supported by the underlying SSL/TLS/DTLS implementation,
           * application name negotiation mechanisms such as <a
           * href="http://www.ietf.org/rfc/rfc7301.txt"> RFC 7301 </a>, the
           * Application-Layer Protocol Negotiation (ALPN), can negotiate
           * application-level values between peers.
           * <p>
           * @implSpec
           * The implementation in this class throws
           * {@code UnsupportedOperationException} and performs no other action.
           *
           * @return null if it has not yet been determined if application
           * protocols might be used for this connection, an empty
           * {@code String} if application protocols values will not
           * be used, or a non-empty application protocol {@code String}
           * if a value was successfully negotiated.
           * @throws UnsupportedOperationException if the underlying provider
           * does not implement the operation.
           * @since 9
           */
          public String getApplicationProtocol() {
              throw new UnsupportedOperationException();
          }

          /**
           * Returns the application protocol value negotiated on a SSL/TLS
           * handshake currently in progress.
           * <p>
           * Like {@link #getHandshakeSession()},
           * a connection may be in the middle of a handshake. The
           * application protocol may or may not yet be available.
           * <p>
           * @implSpec
           * The implementation in this class throws
           * {@code UnsupportedOperationException} and performs no other action.
           *
           * @return null if it has not yet been determined if application
           * protocols might be used for this handshake, an empty
           * {@code String} if application protocols values will not
           * be used, or a non-empty application protocol {@code String}
           * if a value was successfully negotiated.
           * @throws UnsupportedOperationException if the underlying provider
           * does not implement the operation.
           * @since 9
           */
          public String getHandshakeApplicationProtocol() {
              throw new UnsupportedOperationException();
          }
       
      SSLParameters
      =============
       
           /**
           * Returns a prioritized array of application-layer protocol names that
           * can be negotiated over the SSL/TLS/DTLS protocols.
           * <p>
           * The array could be empty (zero-length), in which case protocol
           * indications will not be used.
           * <p>
           * This method will return a new array each time it is invoked.
           *
           * @return a non-null, possibly zero-length array of application protocol
           * {@code String}s. The array is ordered based on protocol
           * preference, with {@code protocols[0]} being the most preferred.
           * @see #setApplicationProtocols
           * @since 9
           */
          public String[] getApplicationProtocols() {
              return applicationProtocols.clone();
          }

          /**
           * Sets the prioritized array of application-layer protocol names that
           * can be negotiated over the SSL/TLS/DTLS protocols.
           * <p>
           * If application-layer protocols are supported by the underlying
           * SSL/TLS implementation, this method configures which values can
           * be negotiated by protocols such as <a
           * href="http://www.ietf.org/rfc/rfc7301.txt"> RFC 7301 </a>, the
           * Application Layer Protocol Negotiation (ALPN).
           * <p>
           * If this end of the connection is expected to offer application protocol
           * values, all protocols configured by this method will be sent to the
           * peer.
           * <p>
           * If this end of the connection is expected to select the application
           * protocol value, the {@code protocols} configured by this method are
           * compared with those sent by the peer. The first matched value becomes
           * the negotiated value. If none of the {@code protocols} were actually
           * requested by the peer, the underlying protocol will determine what
           * action to take. (For example, ALPN will send a
           * {@code "no_application_protocol"} alert and terminate the connection.)
           * <p>
           * @implSpec
           * This method will make a copy of the {@code protocols} array.
           *
           * @param protocols an ordered array of application protocols,
           * with {@code protocols[0]} being the most preferred.
           * If the array is empty (zero-length), protocol
           * indications will not be used.
           * @throws IllegalArgumentException if protocols is null, or if
           * any element in a non-empty array is null or an
           * empty (zero-length) string
           * @see #getApplicationProtocols
           * @since 9
           */
          public void setApplicationProtocols(String[] protocols) {
              if (protocols == null) {
                  throw new IllegalArgumentException("protocols was null");
              }

              String[] tempProtocols = protocols.clone();

              for (String p : tempProtocols) {
                  if (p == null || p.equals("")) {
                      throw new IllegalArgumentException(
                          "An element of protocols was null/empty");
                  }
              }
              applicationProtocols = tempProtocols;
          }


      3. Implementation

      The following existing JSSE implementation classes are enhanced to support handling of an ALPN extension in the TLS client and server Hello messages:

      sun.security.ssl.Alerts.java
      sun.security.ssl.ClientHandshaker.java
      sun.security.ssl.ExtensionType.java
      sun.security.ssl.HandshakeMessage.java
      sun.security.ssl.Handshaker.java
      sun.security.ssl.HelloExtensions.java
      sun.security.ssl.SSLServerSocketImpl.java
      sun.security.ssl.SSLSessionImpl.java
      sun.security.ssl.SSLSocketImpl.java
      sun.security.ssl.ServerHandshaker.java

      Along with a new implementation class:

            sun.security.ssl.ALPNExtension implements HelloExtension


      4. Issues

      ALPN support may be backported to JDK 8 so an implementation is needed that does not introduce any new Java SE 8 APIs. This may require creating something in a jdk.* or com.oracle.ssl.net package.

        Attachments

          Activity

            People

            • Assignee:
              wetmore Bradford Wetmore
              Reporter:
              vinnie Vincent Ryan
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Due:
                Created:
                Updated:
                Resolved: