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.
Note: 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. Be aware, however, 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 CRL on. 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.
gotcha
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.
gotcha
Identifying CRL-specific directives supported in global or server and virtual
host.
See the
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, located in the bin directory of IBM HTTP Server, to create your CRL
password stash file. The password you specify using the sslstash command should equal the one
you use to log in to your LDAP server.
Usage:
sslstash [-c] <directory_to_password_file_and_file_name> <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 will respond 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