From 0a243a228d0d3d4cc765924e455b132e1794d026 Mon Sep 17 00:00:00 2001 From: Artur Barashev Date: Fri, 25 Jul 2025 12:19:02 -0400 Subject: [PATCH 1/4] 8209992: Align SSLSocket and SSLEngine Javadocs --- .../share/classes/javax/net/ssl/SSLEngine.java | 4 ++++ .../share/classes/javax/net/ssl/SSLSocket.java | 10 +++++++--- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/src/java.base/share/classes/javax/net/ssl/SSLEngine.java b/src/java.base/share/classes/javax/net/ssl/SSLEngine.java index 228750e080c25..bc0deaa9d79df 100644 --- a/src/java.base/share/classes/javax/net/ssl/SSLEngine.java +++ b/src/java.base/share/classes/javax/net/ssl/SSLEngine.java @@ -1090,6 +1090,10 @@ public SSLSession getHandshakeSession() { /** * Initiates handshaking (initial or renegotiation) on this SSLEngine. *

+ * For TLSv1.3 and later versions calling this method after the connection + * has been established will force producing a KeyUpdate message. 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 * implicitly call this method if handshaking has not already begun. 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..12943a2e53db2 100644 --- a/src/java.base/share/classes/javax/net/ssl/SSLSocket.java +++ b/src/java.base/share/classes/javax/net/ssl/SSLSocket.java @@ -506,11 +506,15 @@ public abstract void removeHandshakeCompletedListener( * 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 + *

+ * For TLSv1.3 and later versions calling this method after the connection + * has been established will force producing a KeyUpdate message. 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 From d5723cb89116f2ff67def55be3dce1c97a471890 Mon Sep 17 00:00:00 2001 From: Artur Barashev Date: Mon, 28 Jul 2025 10:09:38 -0400 Subject: [PATCH 2/4] Address PR comments --- .../share/classes/javax/net/ssl/SSLEngine.java | 13 +++++++++---- .../share/classes/javax/net/ssl/SSLSocket.java | 16 +++++++++------- 2 files changed, 18 insertions(+), 11 deletions(-) diff --git a/src/java.base/share/classes/javax/net/ssl/SSLEngine.java b/src/java.base/share/classes/javax/net/ssl/SSLEngine.java index bc0deaa9d79df..69d053d95b46a 100644 --- a/src/java.base/share/classes/javax/net/ssl/SSLEngine.java +++ b/src/java.base/share/classes/javax/net/ssl/SSLEngine.java @@ -1088,11 +1088,16 @@ public SSLSession getHandshakeSession() { /** - * Initiates handshaking (initial or renegotiation) on this SSLEngine. + * Initiates handshaking on this SSLEngine. Common reasons include a need + * to initiate a new session, to use new encryption keys or to change + * cipher suites. To force complete reauthentication, the current session + * could be invalidated before starting this handshake. *

- * For TLSv1.3 and later versions calling this method after the connection - * has been established will force producing a KeyUpdate message. For prior - * TLS versions it will force a renegotiation (re-handshake). + * The behavior of this method is protocol (and possibly implementation) + * dependent. For example, in TLSv1.3 and later versions calling this + * method after the connection has been established will force producing + * a KeyUpdate message. 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 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 12943a2e53db2..ca930c7fb83b7 100644 --- a/src/java.base/share/classes/javax/net/ssl/SSLSocket.java +++ b/src/java.base/share/classes/javax/net/ssl/SSLSocket.java @@ -502,14 +502,16 @@ 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. + * Initiates handshaking on this connection. Common reasons include a need + * to initiate a new session, to use new encryption keys or to change + * cipher suites. To force complete reauthentication, the current session + * could be invalidated before starting this handshake. *

- * For TLSv1.3 and later versions calling this method after the connection - * has been established will force producing a KeyUpdate message. For prior - * TLS versions it will force a renegotiation (re-handshake). + * The behavior of this method is protocol (and possibly implementation) + * dependent. For example, in TLSv1.3 and later versions calling this + * method after the connection has been established will force producing + * a KeyUpdate message. 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 From 8cf4e12fca7f5a49ff4c90a429c68561adf66b67 Mon Sep 17 00:00:00 2001 From: Artur Barashev Date: Thu, 31 Jul 2025 14:47:56 -0400 Subject: [PATCH 3/4] Address Brad's code review --- .../share/classes/javax/net/ssl/SSLEngine.java | 17 +++++++++-------- .../share/classes/javax/net/ssl/SSLSocket.java | 17 +++++++++-------- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/src/java.base/share/classes/javax/net/ssl/SSLEngine.java b/src/java.base/share/classes/javax/net/ssl/SSLEngine.java index 69d053d95b46a..5642016952a5f 100644 --- a/src/java.base/share/classes/javax/net/ssl/SSLEngine.java +++ b/src/java.base/share/classes/javax/net/ssl/SSLEngine.java @@ -1088,16 +1088,17 @@ public SSLSession getHandshakeSession() { /** - * Initiates handshaking on this SSLEngine. Common reasons include a need - * to initiate a new session, to use new encryption keys or to change - * cipher suites. To force complete reauthentication, the current session - * could be invalidated before starting this handshake. + * Begins handshaking on this {@code SSLEngine}. + *

+ * 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 and later versions calling this - * method after the connection has been established will force producing - * a KeyUpdate message. For prior TLS versions it will force a - * renegotiation (re-handshake). + * 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 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 ca930c7fb83b7..7da8d26402741 100644 --- a/src/java.base/share/classes/javax/net/ssl/SSLSocket.java +++ b/src/java.base/share/classes/javax/net/ssl/SSLSocket.java @@ -502,16 +502,17 @@ public abstract void removeHandshakeCompletedListener( /** - * Initiates handshaking on this connection. Common reasons include a need - * to initiate a new session, to use new encryption keys or to change - * cipher suites. To force complete reauthentication, the current session - * could be invalidated before starting this handshake. + * 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 and later versions calling this - * method after the connection has been established will force producing - * a KeyUpdate message. For prior TLS versions it will force a - * renegotiation (re-handshake). + * 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 From 5779ff3454a62bdf7555905a487a4db3464c8211 Mon Sep 17 00:00:00 2001 From: Artur Barashev Date: Fri, 1 Aug 2025 11:15:14 -0400 Subject: [PATCH 4/4] Address latest review commants --- src/java.base/share/classes/javax/net/ssl/SSLEngine.java | 3 --- src/java.base/share/classes/javax/net/ssl/SSLSocket.java | 2 +- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/src/java.base/share/classes/javax/net/ssl/SSLEngine.java b/src/java.base/share/classes/javax/net/ssl/SSLEngine.java index 5642016952a5f..9376b7d18765d 100644 --- a/src/java.base/share/classes/javax/net/ssl/SSLEngine.java +++ b/src/java.base/share/classes/javax/net/ssl/SSLEngine.java @@ -1112,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 7da8d26402741..117f2de9bbc6d 100644 --- a/src/java.base/share/classes/javax/net/ssl/SSLSocket.java +++ b/src/java.base/share/classes/javax/net/ssl/SSLSocket.java @@ -521,7 +521,7 @@ public abstract void removeHandshakeCompletedListener( * 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)