JSSE reference guide issue

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

JSSE reference guide issue

Daniel Jeliński
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
Reply | Threaded
Open this post in threaded view
|

Re: JSSE reference guide issue

Sean Mullan
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
>
Reply | Threaded
Open this post in threaded view
|

Re: JSSE reference guide issue

Seán Coffey
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
>>
Reply | Threaded
Open this post in threaded view
|

Re: JSSE reference guide issue

Daniel Jeliński
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
> >>
Reply | Threaded
Open this post in threaded view
|

Re: JSSE reference guide issue

raell
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
Reply | Threaded
Open this post in threaded view
|

Re: JSSE reference guide issue

Daniel Jeliński
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
Reply | Threaded
Open this post in threaded view
|

Re: JSSE reference guide issue

raell
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):

>
> 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
Reply | Threaded
Open this post in threaded view
|

Re: JSSE reference guide issue

Sean Mullan
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
>