JDK-8237486 : Client-side OCSP stapling for JSSE
  • Type: CSR
  • Component: security-libs
  • Sub-Component: javax.net.ssl
  • Priority: P3
  • Status: Draft
  • Resolution: Unresolved
  • Submitted: 2020-01-17
  • Updated: 2020-02-04
Related Reports
CSR :  
Relates :  
Relates :  
Description
Summary
-------
This enhancement will implement client-side OCSP stapling for TLS 1.3 connections.  With this change, JSSE clients that are requested to staple responses may do so.  JSSE servers may now request OCSP stapling from clients and will evaluate stapled responses.

Problem
-------
The initial release of TLS 1.3 in JDK 11 carried forward the original OCSP stapling capabilities from [JEP 249](https://openjdk.java.net/jeps/249), which was server-side stapling only.  While [RFC 8446](https://tools.ietf.org/html/rfc8446) does allow for client-side stapling, it is not required functionality and was omitted in the original release.  With this feature, both clients and servers can request stapling from their peer and can staple responses when requested by their peer.

Solution
--------
The solution separates stapling actions into two functional activities:

1. Requesting stapled OCSP responses from the peer and evaluation of the responses, if provided.
2. Inclusion of stapled responses to be given to the peer.

This grants clients and servers the flexibility to configure a variety of different stapling behaviors.  There are currently two System properties that enable/disable stapling behavior on the client and server (via JEP 249):

* `jdk.tls.client.enableStatusRequestExtension`: On by default, when enabled allows the client to request stapling from the server
* `jdk.tls.server.enableStatusRequestExtension`: Off by default, when enabled allows the server to provide OCSP responses in-band when requested by the client.

These two properties will stay as the client and server properties used to indicate enabled/disabled behavior.  The current allowed values of "true" and "false" will continue to have their meanings as described above.  In addition a new multi-valued property value will be accepted by the JSSE client and server to allow the user to configure the requesting and the providing of OCSP responses separately.

The format for the new multi-valued property is a comma-delimited string.  Acceptable values are:

* request:
    * Client-side: The client will assert the status_request and status_request_v2 extensions in the ClientHello message.
    * Server-side: The server will assert the status_request in the CertificateRequest message (TLS 1.3 only)
* provide:
    * Client-side: The client will provide stapled OCSP responses in its Certificate message if the server has requested it (TLS 1.3 only)
    * Server-side: The server will provide stapled OCSP responses in either the CertificateStatus (TLS 1.2 and earlier) or Certificate messages (TLS 1.3) if the client has requested it. 

Because we are adding new allowed values to the existing properties, but still honoring the old true/false values, the following matrices show how the different acceptable values for each property result in stapling behavior:
<P>

`jdk.tls.client.enableStatusRequestExtension` Behavior:
| Value | Request | Provide |
|:--------|:-------------|:-----------|
| None | enabled | disabled |
| True | enabled | disabled | 
| False | disabled | disabled |
| request | enabled | disabled |
| provide | disabled | enabled |
| request,provide | enabled | enabled |

`jdk.tls.server.enableStatusRequestExtension` Behavior:
| Value | Request | Provide |
|:--------|:-------------|:-----------|
| None | disabled | disabled |
| True | disabled | enabled | 
| False | disabled | disabled |
| request | enabled | disabled |
| provide | disabled | enabled |
| request,provide | enabled | enabled |

There are 6 other stapling-related System properties defined in JEP 249 tied to caching behavior, responder location, etc.  Those will be in effect in all cases and are not affected by the above property logic.  These properties are used for stapling regardless of whether the endpoint is a client or a server.

### TLS 1.2 And Earlier Considerations

Client-side stapling is only allowed in TLS 1.3, and earlier versions of the protocol only support server-side stapling.  It is likely that `SSLSocket` and `SSLEngine` instances will be able to negotiate either TLS 1.2 or TLS 1.3, the determination of which is part of the same handshaking message exchange where some stapling requests take place.  Because of this it should be noted that if a client has the "provide" keyword but negotiates TLS 1.2 or earlier, it will not attempt to staple responses to its Certificate message.  Likewise, a server negotiating these protocols will not request stapling from a client even if its property has the "request" keyword specified.