JEP 124: Enhance the Certificate Revocation-Checking API

Summary

Improve the certificate revocation-checking API to support best-effort checking, single-certificate checking, and mechanism-specific options and parameters.

Goals

1. Provide API support for best-effort checking. With best-effort checking, a certificate is not considered invalid if a connection cannot be made to the server holding the revocation information.

2. Provide API support to independently check the revocation status of a certificate rather than every certificate in the certificate chain.

3. Provide API support for revocation checking options that are currently specified as system properties. Add additional parameters specific to the type of revocation checking mechanism used, CRLs or OCSP.

Motivation

The current java.security.cert API considers a failure to contact the server holding the revocation information to be a fatal error, which is too strict in many environments. A best-effort option would provide a reasonable balance between security and usability and is also supported by many other revocation checking implementations.

The current API is also “all or nothing”, which requires the revocation status of every certificate in the certificate chain to be checked. It does not allow you to check the revocation status of a single certificate, or periodically re-check the revocation status of a certificate without validating the entire chain.

The current API lacks support for specifying options that are specific to a particular revocation mechanism, such as CRLs or OCSP. Currently these options are either missing (such as OCSP nonces) or can only be specified as security properties.

These enhancements will make the API more complete, flexible, and more competitive with other implementations. Many implementations provide additional revocation checking options such as best-effort checking.

Description

This is an initial draft of the API changes to support the goals above.

Add a new RevocationParameters class or interface that holds various parameters that can be specified when requesting revocation. Add subclasses for specifying options specific to OCSP or CRLs, e.g., OCSPParameters and CRLParameters.

Add additional methods to the PKIXParameters class to allow these parameters to be specified.

Add a new RevocationChecker class which can be used for checking the revocation status of a single certificate. It should be possible to specify the revocation checking options of a RevocationChecker with a RevocationParameters object.

The existing certpath debug option will be enhanced to log important issues for debugging purposes (-Djava.security.debug=certpath).

Testing

Unit tests will be created to test the new APIs. It may be necessary to implement OCSP and CRL servers to simulate a proper test environment.

Ideally, each vendor should implement a test suite that checks that a certificate has been revoked for each CA in the vendor-specific cacerts file (since the cacerts file in OpenJDK is empty). This will minimize the risk of failures due to subtle bugs in the implementation or the CA’s deployment. Some CAs will issue test certificates for testing their services; however often these certificates are short-lived and thus would have to be periodically renewed.

Impact

• Documentation: The PKI Programmer’s Guide will need to be updated with the new APIs.

• I18n/L10n: localization of error messages may be required