Summary

Align and clarify SSLSocket and SSLEngine Javadocs

Problem

SSLSocket.startHandshake() and SSLEngine.beginHandshake() are similar in that they start the TLS handshake, but they can also be used after the TLS handshake. SSLSocket.startHandshake() Javadoc seems to be more generic, describing that the method may not only start a new handshake but also be used to update encryption keys etc. In light of TLS 1.3 where renegotiation is forbidden, we would like the Javadoc of these method to align and describe exactly what they do with respect to the TLS protocol version.

Solution

Add a javadoc paragraph to SSLSocket.startHandshake() and SSLEngine.beginHandshake() methods explaining behavioral differences between TLSv1.3+ and TLSv1.2- versions.

Specification

Insert the following javadoc paragraphs to SSLSocket.startHandshake() and SSLEngine.beginHandshake() methods:

 * <P>
 * Common reasons include a need to initiate a new protected session,
 * create new encryption keys, or to change cipher suites. To force
 * complete reauthentication, the current session should be invalidated
 * before starting this handshake.
 * <P>
 * The behavior of this method is protocol (and possibly implementation)
 * dependent. For example, in TLSv1.3 calling this method after the
 * connection has been established will force a key update. For prior TLS
 * versions it will force a renegotiation (re-handshake).