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 |
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 > |
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 >> |
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 > >> |
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 |
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 |
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 |
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 > |
Free forum by Nabble | Edit this page |