+ * 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. + *
+ * 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). *
* This method is not needed for the initial handshake, as the * {@code wrap()} and {@code unwrap()} methods will @@ -1102,9 +1112,6 @@ public SSLSession getHandshakeSession() { * SSLSocket#startHandshake()} method, this method does not block * until handshaking is completed. *
- * To force a complete SSL/TLS/DTLS session renegotiation, the current - * session should be invalidated prior to calling this method. - *
* Some protocols may not support multiple handshakes on an existing * engine and may throw an {@code SSLException}. * diff --git a/src/java.base/share/classes/javax/net/ssl/SSLSocket.java b/src/java.base/share/classes/javax/net/ssl/SSLSocket.java index a18c203320d22..117f2de9bbc6d 100644 --- a/src/java.base/share/classes/javax/net/ssl/SSLSocket.java +++ b/src/java.base/share/classes/javax/net/ssl/SSLSocket.java @@ -502,19 +502,26 @@ public abstract void removeHandshakeCompletedListener( /** - * Starts an SSL handshake on this connection. Common reasons include - * a need to use new encryption keys, to change cipher suites, or to - * initiate a new session. To force complete reauthentication, the - * current session could be invalidated before starting this handshake. - * - *
If data has already been sent on the connection, it continues + * Starts handshaking on this {@code SSLSocket}. + *
+ * 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. + *
+ * 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). + *
+ * If data has already been sent on the connection, it continues * to flow during this handshake. When the handshake completes, this * will be signaled with an event. - * + *
* This method is synchronous for the initial handshake on a connection * and returns when the negotiated handshake is complete. Some * protocols may not support multiple handshakes on an existing socket - * and may throw an IOException. + * and may throw an {@code IOException}. * * @throws IOException on a network level error * @see #addHandshakeCompletedListener(HandshakeCompletedListener)