RFR: JEP 249 (OCSP Stapling for TLS)

[Xuelei Fan]

src/java.base/share/classes/javax/net/ssl/ExtendedSSLSession.java
=================================================================
-  * Obtains a {@link List} containing all status responses presented by
-  * the peer.
+  * Obtains a {@link List} containing DER-encoded OCSP responses
+  * (using the ASN.1 type OCSPResponse defined in RFC 6960) for
+  * the client to verify status of the server's certificate during
+  * handshaking.

As this method can be called from both client and server side, "by the
peer" may be confusing.

Better to indicate the encode.  Alternatively, the encode can also be
specified in return value description.

----------------------------

-  * In server mode, the call will return an empty {@link List}
-  * as the client does not present status responses in a
-  * CertificateStatus message.
-  * <P>
-  * In client mode, a {@link List} containing one or more status
-  * responses will be returned if the server sent responses in a
-  * CertificateStatus handshake message.  Otherwise an empty
-  * {@link List} will be returned.

I think, actually there is no difference of the return value for client
side and server side.  Easy to understand if joining them together.
Maybe better move to the return value description.

Better to describe the sequence of the returned value and the item may
be empty (not null) in order to follow the spec at the end paragraph of
page 6, RFC 6961.

----------------------------
-  * If one or more responses have been set, {@link
-  * X509ExtendedTrustManager} objects will attempt to use them
-  * during server certificate verification.
-  * <P>
-  * Note: This method can be used only when using certificate-based
-  * cipher suites; using it with non-certificate-based cipher suites,
-  * such as Kerberos, will return an empty {@link List}.
+  * This method only apply to certificate-based server
+  * authentication.  {@code X509ExtendedTrustManager} will use the
+  * returned value for server certificates validation.

"certificate-based authentication" is a more general expression than
"certificate-based cipher suites".  Kerberos may also use certicate, I
would suggest to remove the example.

----------------------------

-  * @return a non-null immutable list of byte arrays, each entry
-  *         containing a single status response.
+  * @return a non-null immutable list of byte arrays, each entry
+  *         containing a DER-encoded OCSP response (using the
+  *         ASN.1 type OCSPResponse defined in RFC 6960) for
+  *         server certificate(s)  authentication.  The returned
+  *         list may be empty if no OCSP response was presented
+  *         during handshaking.

Just for your consideration.

Xuelei

On 6/19/2015 8:27 AM, Jamil Nimeh wrote:
> Hello all,
> 
> I have a first cut at the OCSP stapling webrev posted for your review:
> 
> JEP: https://bugs.openjdk.java.net/browse/JDK-8046321
> Webrev: http://cr.openjdk.java.net/~jnimeh/reviews/8046321/webrev.0/
> 
> A couple items to note:
> 
>   * I'm in the process of updating the JEP with some more details.  I
>     should be done with these changes by tonight (PDT).
>   * Missing are some of the TLS end-to-end tests.  These tests have been
>     coded and run outside the jtreg framework, but for some reason
>     things hang in jtreg.  I've included some of the supporting classes
>     that these tests will use (CertificateBuilder.java and
>     SimpleOCSPResponder.java) so folks could review those if they're
>     interested.  I will update the webrev and notify the list as soon as
>     I've got the tests working in jtreg.
> 
> Thanks to everyone who has helped along the way.
> 
> --Jamil
> 
>