Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8282768

Fix API Note in javadoc for javax.net.ssl.SSLSocket

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 19
    • Component/s: security-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Fixes incorrect documentation which will be apparent if anyone tries to use this note.
    • Interface Kind:
      Java API
    • Scope:
      Implementation

      Description

      Summary

      An API Note was introduced by JDK-8208526 that described the new closing behavior of SSLSocket for TLSv1.3. Subsequent work done by JDK-8216326 reverted the implementation behavior to match that of Sockets and previous SSLSockets (pre-JDK11), but the API Note was not updated to reflect the correct behavior.

      Problem

      The existing @apiNote is incorrect and out of date.

      (Apparently CSRs are not needed for @apiNotes, but will complete one for visibility and reviewer eyes.)

      Solution

      In order to support TLSv1.3 1/2 closed sockets, JDK-8207009(bug)/JDK-8208526(CSR) introduced behavior into the JDK 11 APIs and implementations which was not consistent with the normal behavior of InputStream/OutputStreams created by Sockets and SSLSockets. Closing a Socket's InputStream/OutputStream is expected to close the associated underlying Socket.

      java.net.Socket
      public OutputStream getOutputStream() throws IOException
      
      Returns an output stream for this socket. 
      ...deleted...
      Closing the returned OutputStream will close the associated socket.

      With JDK-8207009, calling InputStream/OutputStream.close() did not close the underlying SSLSocket, only the input or output side.

      This was later noticed by JDK-8216326, which fixed the incorrect behavior in 13 and was backported to 11.0.5. This change probably should have had a CSR, but I am unable to find one for it. Unfortunately, the incorrect API documentation was not noticed during JDK-8216326 and has remained.

      Specification

      Change the @apiNote in javax.net.ssl.SSLSocket.java

      src/java.base/share/classes/javax/net/ssl/SSLSocket.java
      @@ -172,21 +172,23 @@
        * </pre></blockquote>
        *
        * @apiNote
        * When the connection is no longer needed, the client and server
        * applications should each close both sides of their respective connection.
      - * For {@code SSLSocket} objects, for example, an application can call
      - * {@link Socket#shutdownOutput()} or {@link java.io.OutputStream#close()}
      - * for output stream close and call {@link Socket#shutdownInput()} or
      - * {@link java.io.InputStream#close()} for input stream close.  Note that
      - * in some cases, closing the input stream may depend on the peer's output
      - * stream being closed first.  If the connection is not closed in an orderly
      - * manner (for example {@link Socket#shutdownInput()} is called before the
      - * peer's write closure notification has been received), exceptions may
      - * be raised to indicate that an error has occurred.  Once an
      - * {@code SSLSocket} is closed, it is not reusable: a new {@code SSLSocket}
      - * must be created.
      + * This can be done either in one shot by calling {@link Socket#close()},
      + * or by closing each side individually using
      + * {@link Socket#shutdownOutput()} / {@link Socket#shutdownInput()} which is
      + * useful for protocol versions that can support half-closed connections.
      + *
      + * <P> Note that in some cases, closing the input stream may depend on the
      + * peer's output stream being closed first.  If the connection is not closed
      + * in an orderly manner (for example {@link Socket#shutdownInput()} is called
      + * before the peer's write closure notification has been received), exceptions
      + * may be raised to indicate that an error has occurred.
      + *
      + * <P> Once an {@code SSLSocket} is closed, it is not reusable: a new
      + * {@code SSLSocket} must be created.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              wetmore Bradford Wetmore
              Reporter:
              jwaters Julian Waters
              Reviewed By:
              Xuelei Fan
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: