OpenJDK › OpenJDK Security Development

JSSE reference guide issue

Classic

List

Threaded

8 messages Options

Daniel Jeliński

JSSE reference guide issue

Hi all,
What's the right spot to report documentation issues?

I've been reading the JSSE reference guide and noticed that in section
"Resuming Session Without Server-Side State"
(https://docs.oracle.com/en/java/javase/15/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-64D7EAF6-D2EE-4719-8616-25E2829CF810)
it says "This feature is not enabled by default", which appears to be
a leftover from Java 13.

Also the note about TLS 1.3 in the same section isn't entirely clear
to me. What does it mean when the docs say "the contents of stateless
tickets, in particular, the contents of a NewSessionTicket message,
depend on the value of jdk.tls.server.enableSessionTicketExtension"?
How exactly does the contents change and why should I care?
Regards,
Daniel

Sean Mullan

Re: JSSE reference guide issue

If you have a JBS account, you can file a bug in the docs/guides category.

However, I have also forwarded your email to our internal docs engineer,
so we will follow-up on it.

Thanks,
Sean

On 2/5/21 2:42 AM, Daniel Jeliński wrote:

> Hi all,
> What's the right spot to report documentation issues?
>
> I've been reading the JSSE reference guide and noticed that in section
> "Resuming Session Without Server-Side State"
> (https://docs.oracle.com/en/java/javase/15/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-64D7EAF6-D2EE-4719-8616-25E2829CF810)
> it says "This feature is not enabled by default", which appears to be
> a leftover from Java 13.
>
> Also the note about TLS 1.3 in the same section isn't entirely clear
> to me. What does it mean when the docs say "the contents of stateless
> tickets, in particular, the contents of a NewSessionTicket message,
> depend on the value of jdk.tls.server.enableSessionTicketExtension"?
> How exactly does the contents change and why should I care?
> Regards,
> Daniel
>

Seán Coffey

Re: JSSE reference guide issue

Another option for reporting is to use the https://bugreport.java.com
portal. Component = documentation.

regards,
Sean.

On 05/02/2021 14:03, Sean Mullan wrote:

> If you have a JBS account, you can file a bug in the docs/guides
> category.
>
> However, I have also forwarded your email to our internal docs
> engineer, so we will follow-up on it.
>
> Thanks,
> Sean
>
> On 2/5/21 2:42 AM, Daniel Jeliński wrote:
>> Hi all,
>> What's the right spot to report documentation issues?
>>
>> I've been reading the JSSE reference guide and noticed that in section
>> "Resuming Session Without Server-Side State"
>> (https://docs.oracle.com/en/java/javase/15/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-64D7EAF6-D2EE-4719-8616-25E2829CF810)
>>
>> it says "This feature is not enabled by default", which appears to be
>> a leftover from Java 13.
>>
>> Also the note about TLS 1.3 in the same section isn't entirely clear
>> to me. What does it mean when the docs say "the contents of stateless
>> tickets, in particular, the contents of a NewSessionTicket message,
>> depend on the value of jdk.tls.server.enableSessionTicketExtension"?
>> How exactly does the contents change and why should I care?
>> Regards,
>> Daniel
>>

Daniel Jeliński

Re: JSSE reference guide issue

Thanks! I didn't think of checking the bug report page. Will keep it in mind.
Regards,
Daniel

pt., 5 lut 2021 o 15:40 Seán Coffey <[hidden email]> napisał(a):

>
> Another option for reporting is to use the https://bugreport.java.com
> portal. Component = documentation.
>
> regards,
> Sean.
>
> On 05/02/2021 14:03, Sean Mullan wrote:
> > If you have a JBS account, you can file a bug in the docs/guides
> > category.
> >
> > However, I have also forwarded your email to our internal docs
> > engineer, so we will follow-up on it.
> >
> > Thanks,
> > Sean
> >
> > On 2/5/21 2:42 AM, Daniel Jeliński wrote:
> >> Hi all,
> >> What's the right spot to report documentation issues?
> >>
> >> I've been reading the JSSE reference guide and noticed that in section
> >> "Resuming Session Without Server-Side State"
> >> (https://docs.oracle.com/en/java/javase/15/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-64D7EAF6-D2EE-4719-8616-25E2829CF810)
> >>
> >> it says "This feature is not enabled by default", which appears to be
> >> a leftover from Java 13.
> >>
> >> Also the note about TLS 1.3 in the same section isn't entirely clear
> >> to me. What does it mean when the docs say "the contents of stateless
> >> tickets, in particular, the contents of a NewSessionTicket message,
> >> depend on the value of jdk.tls.server.enableSessionTicketExtension"?
> >> How exactly does the contents change and why should I care?
> >> Regards,
> >> Daniel
> >>

raell

Re: JSSE reference guide issue

In reply to this post by Daniel Jeliński

Concerning the question:

>Also the note about TLS 1.3 in the same section isn't entirely clear
to me. What does it mean when the docs say "the contents of stateless
>tickets, in particular, the contents of a NewSessionTicket message,
>depend on the value of jdk.tls.server.enableSessionTicketExtension"?

In TLS 1.3, if stateless session resumption is in use (i.e.
jdk.tls.server.enableSessionTicketExtension=true) the NewSessionTicket message
includes all session information (in encrypted format). If session resumption is
stateful (i.e. jdk.tls.server.enableSessionTicketExtension=false), the
NewSessionTicket message just contains a key that is used by the server during session
resumption in order to access the session information from its session cache.

>why should I care?

The point is: In TLS 1.3 the resumption mode (stateful/stateless) can be configured
by the property jdk.tls.server.enableSessionTicketExtension (though there is no
SessionTicketExtension extension in TLS 1.3). But in JDK 14 or later,
there is usually no need to change the default (=stateless).

Regards,

Ralph

Gesendet: Freitag, 05. Februar 2021 um 08:42 Uhr
Von: "Daniel Jeliński" <[hidden email]>
An: [hidden email]
Betreff: JSSE reference guide issue
Hi all,
What's the right spot to report documentation issues?

I've been reading the JSSE reference guide and noticed that in section
"Resuming Session Without Server-Side State"
(https://docs.oracle.com/en/java/javase/15/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-64D7EAF6-D2EE-4719-8616-25E2829CF810)
it says "This feature is not enabled by default", which appears to be
a leftover from Java 13.

Also the note about TLS 1.3 in the same section isn't entirely clear
to me. What does it mean when the docs say "the contents of stateless
tickets, in particular, the contents of a NewSessionTicket message,
depend on the value of jdk.tls.server.enableSessionTicketExtension"?
How exactly does the contents change and why should I care?
Regards,
Daniel

Daniel Jeliński

Re: JSSE reference guide issue

Thanks Ralph. I figured that out already. However, the docs are
(still) a bit misleading here. Let me quote:

> For TLS 1.3, stateless tickets use the existing PSK resumption extension. Therefore, session resumption **without server-site** state doesn't require these two properties. However, the contents of **stateless** tickets, in particular, the contents of a NewSessionTicket message, depend on the value of jdk.tls.server.enableSessionTicketExtension.
(emphasis mine)

The server can use PSK for either stateful or stateless tickets, and
the choice is solely at the server's discretion, the client has no
choice here. However, the paragraph above suggests that we will not
have any server side state even with
jdk.tls.server.enableSessionTicketExtension=false, and that the
property will only change the stateless session ticket contents in
some unspecified way. I think we should use different wording here.
Regards,
Daniel

śr., 24 mar 2021 o 12:38 <[hidden email]> napisał(a):

>
> Concerning the question:
>
> >Also the note about TLS 1.3 in the same section isn't entirely clear
> to me. What does it mean when the docs say "the contents of stateless
> >tickets, in particular, the contents of a NewSessionTicket message,
> >depend on the value of jdk.tls.server.enableSessionTicketExtension"?
>
> In TLS 1.3, if stateless session resumption is in use (i.e.
> jdk.tls.server.enableSessionTicketExtension=true) the NewSessionTicket message
> includes all session information (in encrypted format). If session resumption is
> stateful (i.e. jdk.tls.server.enableSessionTicketExtension=false), the
> NewSessionTicket message just contains a key that is used by the server during session
> resumption in order to access the session information from its session cache.
>
> >why should I care?
>
> The point is: In TLS 1.3 the resumption mode (stateful/stateless) can be configured
> by the property jdk.tls.server.enableSessionTicketExtension (though there is no
> SessionTicketExtension extension in TLS 1.3). But in JDK 14 or later,
> there is usually no need to change the default (=stateless).
>
> Regards,
>
> Ralph
>
>
>
> Gesendet: Freitag, 05. Februar 2021 um 08:42 Uhr
> Von: "Daniel Jeliński" <[hidden email]>
> An: [hidden email]
> Betreff: JSSE reference guide issue
> Hi all,
> What's the right spot to report documentation issues?
>
> I've been reading the JSSE reference guide and noticed that in section
> "Resuming Session Without Server-Side State"
> (https://docs.oracle.com/en/java/javase/15/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-64D7EAF6-D2EE-4719-8616-25E2829CF810)
> it says "This feature is not enabled by default", which appears to be
> a leftover from Java 13.
>
> Also the note about TLS 1.3 in the same section isn't entirely clear
> to me. What does it mean when the docs say "the contents of stateless
> tickets, in particular, the contents of a NewSessionTicket message,
> depend on the value of jdk.tls.server.enableSessionTicketExtension"?
> How exactly does the contents change and why should I care?
> Regards,
> Daniel

raell

Re: JSSE reference guide issue

Hi Daniel,

I agree that the doc is a bit misleading. Maybe, the TLS 1.2 part can be put into the note:

----------------------
jdk.tls.server.enableSessionTicketExtension: Enables a server to use stateless session
tickets. A value of true (default value) enables the use of stateless session tickets,
false does not.

Note: In TLS 1.2 stateless session tickets will be used only if they are supported by the client.
---------------------

Regards

Ralph

Gesendet: Mittwoch, 24. März 2021 um 16:29 Uhr
Von: "Daniel Jeliński" <[hidden email]>
An: [hidden email]
Cc: [hidden email]
Betreff: Re: JSSE reference guide issue
Thanks Ralph. I figured that out already. However, the docs are
(still) a bit misleading here. Let me quote:

> For TLS 1.3, stateless tickets use the existing PSK resumption extension. Therefore, session resumption **without server-site** state doesn't require these two properties. However, the contents of **stateless** tickets, in particular, the contents of a NewSessionTicket message, depend on the value of jdk.tls.server.enableSessionTicketExtension.
(emphasis mine)

The server can use PSK for either stateful or stateless tickets, and
the choice is solely at the server's discretion, the client has no
choice here. However, the paragraph above suggests that we will not
have any server side state even with
jdk.tls.server.enableSessionTicketExtension=false, and that the
property will only change the stateless session ticket contents in
some unspecified way. I think we should use different wording here.
Regards,
Daniel

śr., 24 mar 2021 o 12:38 <[hidden email]> napisał(a):

Sean Mullan

Re: JSSE reference guide issue

In reply to this post by raell

> I've been reading the JSSE reference guide and noticed that in section
> "Resuming Session Without Server-Side State"
>
(https://docs.oracle.com/en/java/javase/15/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-64D7EAF6-D2EE-4719-8616-25E2829CF810)
> it says "This feature is not enabled by default", which appears to be
> a leftover from Java 13.

That was fixed in the JDK 16 docs:

https://docs.oracle.com/en/java/javase/16/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-64D7EAF6-D2EE-4719-8616-25E2829CF810

I have forwarded your other suggestions for improvements to our docs writer.

Thanks,
Sean

On 3/24/21 7:38 AM, [hidden email] wrote:

> Concerning the question:
>
>> Also the note about TLS 1.3 in the same section isn't entirely clear
> to me. What does it mean when the docs say "the contents of stateless
>> tickets, in particular, the contents of a NewSessionTicket message,
>> depend on the value of jdk.tls.server.enableSessionTicketExtension"?
>
> In TLS 1.3, if stateless session resumption is in use (i.e.
> jdk.tls.server.enableSessionTicketExtension=true) the NewSessionTicket message
> includes all session information (in encrypted format). If session resumption is
> stateful (i.e. jdk.tls.server.enableSessionTicketExtension=false), the
> NewSessionTicket message just contains a key that is used by the server during session
> resumption in order to access the session information from its session cache.
>
>> why should I care?
>
> The point is: In TLS 1.3 the resumption mode (stateful/stateless) can be configured
> by the property jdk.tls.server.enableSessionTicketExtension (though there is no
> SessionTicketExtension extension in TLS 1.3). But in JDK 14 or later,
> there is usually no need to change the default (=stateless).
>
> Regards,
>
> Ralph
>
>
>
> Gesendet: Freitag, 05. Februar 2021 um 08:42 Uhr
> Von: "Daniel Jeliński" <[hidden email]>
> An: [hidden email]
> Betreff: JSSE reference guide issue
> Hi all,
> What's the right spot to report documentation issues?
>
> I've been reading the JSSE reference guide and noticed that in section
> "Resuming Session Without Server-Side State"
> (https://docs.oracle.com/en/java/javase/15/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-64D7EAF6-D2EE-4719-8616-25E2829CF810)
> it says "This feature is not enabled by default", which appears to be
> a leftover from Java 13.
>
> Also the note about TLS 1.3 in the same section isn't entirely clear
> to me. What does it mean when the docs say "the contents of stateless
> tickets, in particular, the contents of a NewSessionTicket message,
> depend on the value of jdk.tls.server.enableSessionTicketExtension"?
> How exactly does the contents change and why should I care?
> Regards,
> Daniel
>