Summary

This change seeks to clarify the behavior of the SSLSession.getValue() method after TLS session resumption via the use of stateless session tickets.

Problem

The behavior of SSLSession.getValue() can change when TLS stateless session tickets are enabled on the server side. With stateless tickets disabled, values set via the putValue() method will be preserved across resumed sessions as the sessions are managed by the server. However, the stateless ticketing feature is enabled by default. When enabled on the server, a client also enabling this feature during the handshaking process will cause any SSLSession values to be omitted when creating stateless tickets. This is the intended behavior, but it is not documented anywhere.

The goal of this change is to provide additional information to the developer for the SunJSSE implementation's use of the jdk.tls.server.enableSessionTicket System property and its impacts on the return value of the getValue() method after a session has been resumed with a stateless session ticket.

Solution

The proposed solution is an implNote added to the SSLSession.getValue() method which explains how the jdk.tls.server.enableSessionTicketExtension System property can impact the return value from these methods, and that the behavior can vary depending on the client's willingness to use stateless session tickets for TLS resumption.

Another solution would be to expand on the section related to stateless session tickets in the "Java Secure Socket Extension (JSSE) Reference Guide"

Specification

diff --git a/src/java.base/share/classes/javax/net/ssl/SSLSession.java b/src/java.base/share/classes/javax/net/ssl/SSLSession.java
index 3e1a2b94c0a..f3fd03250ec 100644
--- a/src/java.base/share/classes/javax/net/ssl/SSLSession.java
+++ b/src/java.base/share/classes/javax/net/ssl/SSLSession.java
@@ -176,6 +176,14 @@ public interface SSLSession {
      * For security reasons, the same named values may not be
      * visible across different access control contexts.
      *
+     * @implNote
+     * When stateless session tickets are used by SunJSSE, bound values set by
+     * {@link SSLSession#putValue(String, Object)} are not retained for resumed
+     * sessions.  If maintaining bound values across resumed sessions is a
+     * requirement then the
+     * {@systemProperty jdk.tls.server.enableSessionTicketExtension} should be
+     * set to false.
+     *
      * @param name the name of the binding to find.
      * @return the value bound to that name, or null if the binding does
      *          not exist.