SSL Certificate revocation list and Online Certificate Status Protocol

Learn about configuring certificate revocation checking for client certificates. Certificate revocation list (CRL) is a deprecated feature. You can use Online Certificate Status Protocol (OCSP) with TLS certificates.

Deprecated feature: Certificate revocation list (CRL) is a deprecated feature. Use Online Certificate Status Protocol (OCSP) with TLS certificates.

Certificate revocation provides the ability to revoke a client certificate that is given to IBM® HTTP Server by the browser when the key becomes compromised, or when access permission to the key gets revoked. The two following protocols perform revocation checking.

Certificate Revocation List (CRL), (deprecated): A database that contains a list of certificates that are revoked before their scheduled expiration date.
Online Certificate Status Protocol (OCSP): An HTTP-based service that is used to check whether an individual certificate was revoked before the scheduled expiration date.

If you want to enable certificate revocation in IBM HTTP Server, publish the CRL on a Lightweight Directory Access Protocol (LDAP) server. Once the CRL is published to an LDAP server, you can access the CRL using the IBM HTTP Server configuration file. The CRL determines the access permission status of the requested client certificate. However, be aware that it's not always possible to determine the revocation status of a client certificate if the backend server, the source of revocation data, is not available or not communicating properly with IBM HTTP Server.

The CRL option turns CRL on and off inside an SSL virtual host. If you specify CRL as an option, then you elect to turn on CRL. If you do not specify CRL as an option, then CRL remains off. If the first option for SSLClientAuth equals 0/none, then you cannot use the second option, CRL. If you do not have client authentication on, then CRL processing does not take place.

Certification revocation information is supplied by the following different sources:

A webserver administrator can aggregate revocation info from multiple sources and explicitly configure that location
- For OCSP, the SSLOCSPResponderURL directive configures this source.
- For CRL, the SSLCRLHostname directive and the optional crl argument to the SSLClientAuth directive configures this source.
A certificate authority can embed the authoritative source of revocation information in each certificate it issues.
- For CRL, this source is only used when the explicitly configured source is configured.
- For OCSP, SSLOCSPEnable configures the processing these sources.
Avoid trouble: It is not always possible to determine the revocation status of a client certificate if the backend server, the source of revocation data, is not available or not communicating properly with IBM HTTP Server. See the "SSLUnknownRevocationStatus" directive to configure how the server behaves in such an event.

Avoid trouble: If your certificates use the LDAP or HTTP URI forms of the CertificateDistributionPoint or AIA extensions, be sure that the IBM HTTP Server system can establish outgoing connections of this type; you might need to adjust the settings for your firewall.

Identifying CRL-specific directives supported in global or server and virtual host.

See the Secure Sockets Layer (SSL) directives for more information about configuring OCSP. Global server and virtual host support the following directives:

SSLCRLHostname: The IP address and host of the LDAP server, where the CRL database resides. Currently, you must configure any static CRL repositories to allow for checking of other URI forms in the CRLDistributionPoint fields.
Only an explicitly configured LDAP server can be queried for CRL, and the SSL handshake fails if the backend server is not reachable.
SSLCRLPort: The port of the LDAP server where the CRL database resides; the default equals 389.
SSLCRLUserID: The user ID to send to the LDAP server where the CRL database resides; defaults to anonymous if you do not specify the bind.
SSLStashfile: The fully qualified path to file where the password for the user name on the LDAP server resides. This directive is not required for an anonymous bind. Use when you specify a user ID.
Use the sslstash command that is located in the bin directory of IBM HTTP Server, to create your CRL password stash file. The password that you specify using the sslstash command should equal the one you use to log in to your LDAP server.
Usage:
```
sslstash [-c] &ltdirectory_to_password_file_and_file_name&gt; <function_name> <password>
```
where:
- -c: Creates a new stash file. If not specified, an existing file updates.
- File: Represents the fully qualified name of the file to create, or update.
- Function: Indicates the function for which to use the password. Valid values include crl, or crypto.
- Password: Represents the password to stash.
SSLUnknownRevocationStatus: This directive allows you to configure how IBM HTTP Server responds when fresh Certificate Revocation List (CRL) information or OCSP (Online Certificate Status Protocol) information is not available, and the client certificate that is currently offered is not known to be revoked from a previous query. Certificates are presumed not to be revoked, by default, which means they are valid, and a temporary failure to obtain CRL or OCSP information does not automatically result in an SSL handshake failure. This directive is provided to respond to circumstances in which a certificate has been accepted without IBM HTTP Server being able to reliably confirm the revocation status.
This directive has an effect only when all of these conditions are true:
- IBM HTTP Server is configured to accept client certificates with the SSLClientAuth directive.
- IBM HTTP Server is configured with one of the following directives: SSLOCSPEnable, SSLOCSPUrl, or SSLCRLHostname.
- An SSL client certificate is provided.
- IBM HTTP Server does not receive a valid OCSP or CRL response from the configured backend server, and the client certificate does not appear as revoked in a cached, but expired, CRL response.
  IBM HTTP Server uses a cached CRL that is beyond its published expiration time when a current version is not available. When a certificate has been revoked in such an expired CRL, this will result in a direct SSL handshake failure that is outside the scope of the SSLUnknownRevocationStatus directive.

CRL checking follows the URIDistributionPoint X509 extension in the client certificate as well as trying the DN constructed from the issuer of the client certificate. If the certificate contains a CRL Distribution Point (CDP), then that information is given precedence. The order in which the information is used is as follows:

CDP LDAP X.500 name
CDP LDAP URI
Issuer name combined with the value from the SSLCRLHostname directive