6.5. Enabling Revocation Checking

⁠6.5. Enabling Revocation Checking

Revocation checking means that a Certificate System subsystem verifies that a certificate is both valid and not revoked when an agent or administrator attempts to access the instance's secure interfaces. This leverages a local OCSP service (either a CA's internal OCSP service or a separate OCSP responder) to check the revocation status of the certificate.

OCSP configuration is covered in Section 6.6, “Using the Online Certificate Status Protocol Responder”.

⁠6.5.1. Enabling Automatic Revocation Checking on the CA

The CA can be configured to check the revocation status of any certificate (including agent, administrator, and enrollment) the server receives during SSL client authentication. This means that when the CA receives any client authentication request, it automatically checks an OCSP. (For information about setting up an OCSP responder, see Section 6.6, “Using the Online Certificate Status Protocol Responder”.)

As part of revocation checking, the CA has the ability to cache client authentication so that it keeps a list of verified certificates. This allows the CA to check its cached results before checking its internal database or an OCSP, which improves the overall operation performance. Automatic revocation checking is enabled in the revocationChecking.enabled parameter.

The revocation status results are only valid for a certain, specified period of time (revocationChecking.validityInterval). If the CA has no way to re-verify a certificate status that is in cache, then there is a grace interval (revocationChecking.unknownStateInterval) where the previously-cached status is still considered valid, even if it is outside the validity interval.

NOTE

The cached certificates are kept in a buffer (revocationChecking.bufferSize). If the buffer setting is missing or is set to zero, then no buffer is kept, which means that the results of revocation checks are not cached. In that case, all revocation checks are performed directly against the CA's internal database.

NOTE

The subsystem CS.cfg configuration file includes a parameter, jss.ocspcheck.enable, which sets whether a Certificate Manager should use an OCSP to verify the revocation status of the certificate it receives as a part of SSL client or server authentication. Changing the value of this parameter to true means the Certificate Manager reads the Authority Information Access extension in the certificate and verifies the revocation status of the certificate from the OCSP responder specified in the extension.

Stop the subsystem instance.
```
service pki-ca stop
```
Open the CS.cfg file.
```
vim /var/lib/pki-ca/conf/CS.cfg
```
Edit the revocation-related parameters.
```
auths.revocationChecking.bufferSize=50
auths.revocationChecking.ca=ca
auths.revocationChecking.enabled=true
auths.revocationChecking.unknownStateInterval=0
auths.revocationChecking.validityInterval=120
```
- revocationChecking.ca. Sets which service is providing the OCSP respsonse, a CA or an OCSP responder.
- revocationChecking.enabled. Sets revocation checking. true enables checking; false disables checking. By default, the feature is enabled.
- revocationChecking.bufferSize. Sets the total number of last-checked certificates the server should maintain in its cache. For example, if the buffer size is 2, the server retains the last two certificates checked in its cache. By default, the server caches the last 50 certificates.
- revocationChecking.unknownStateInterval. Sets how frequently the server checks the revocation status. The default interval is 0 seconds. unknownStateInterval is a grace period in which cache result will be assumed to be true if CA has no means (no access to information allowing) to verify certificate status
- revocationChecking.validityInterval. Sets how long the cached certificates are considered valid. Be judicious when choosing the interval. For example, if the validity period is 60 seconds, the server discards the certificates in its cache every minute and attempts to retrieve them from their source. The Certificate Manager uses its internal database to retrieve and verify the revocation status of the certificates. The default validity period is 120 seconds (2 minutes).
Start the Certificate System instance.
```
service pki-ca start
```

⁠6.5.2. Enabling Certificate Revocation Checking for DRM, OCSP, and TKS Users

The Java subsystems (DRM, OCSP, and TKS) do not have OCSP checking enabled, by default, to validate subsystem certificates. This means it is possible for someone to log into the administrative or agent interfaces with a revoked certificate.

OCSP checking can be enabled for DRM, OCSP, and TKS instances very easily by editing the server.xml file. The agent interface and the admin interface are configured separately, so both sections in the configuration should be edited.

NOTE

If the subsystem instance has been configured to use an SSL connection with its internal database, then the LDAP internal database's SSL server certificate must be recognized by the OCSP responder. If the OCSP responder does not recognize the LDAP server certificate, then the subsystem will not start properly. This configuration is covered in the Certificate System Installation Guide, since subsystem-LDAP SSL server connections are configured as part of the subsystem setup.

Get the name of the OCSP signing certificate for the OCSP or CA which will be used to check certificate status. For example:

# certutil -L -d /var/lib/pki-ocsp/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

Certificate Authority - Example Domain                       CT,c,
ocspSigningCert cert-pki-ocsp CTu,Cu,Cu
subsystemCert cert-pki-ocsp                                  u,u,u
Server-Cert cert-pki-ocsp                                    u,u,u
auditSigningCert cert-pki-ocsp                               u,u,Pu

Open the server.xml file for the subsystem. For example:
```
vim /var/lib/pki-kra/conf/server.xml
```
The OCSP signing certificate must be imported into the subsystems's security database. For example, for the DRM:
```
certutil -d /var/lib/pki-kra/alias -A -n "ocspSigningCert cert-pki-ca" -t "C,," -a -i ocspCert.b64
```
There are three critical parameters to enable OCSP checking:
- enableOCSP, which must be set to true to enable OCSP checking.
  This is a global setting; if it is set for one interface, then it applies to every interface for the instance. However, it must be set on the first interface listed in the server.xml file, which is usually the agent interface. Any setting on another interface is ignored.
- ocspResponderURL, which gives the URL of the OCSP responder to send the OCSP requests.
  For an OCSP Manager, this can be its own internal service or another OCSP service in another OCSP or in a CA. For a TKS or DRM, this always points to an external OCSP service in an OCSP or a CA.
- ocspResponderCertNickname, which gives the signing certificate to use to sign the response; for a CA OCSP service, this is the CA's OCSP signing certificate, and for an OCSP responder, it is an OCSP signing certificate.
Other parameters can be used to define the OCSP communication. All of the OCSP checking parameters are listed in Table 6.2, “OCSP Parameters for server.xml”.
There are two different sections in the file for the agent and administrator interfaces. The OCSP parameters need to be added to both sections to enable and configure OCSP checking. For example:
⁠
Example 6.1. OCSP Settings for an Agent Interface
```
<Connector name="Agent" port="10443" maxHttpHeaderSize="8192"
        maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
        enableLookups="false" disableUploadTimeout="true"
        acceptCount="100" scheme="https" secure="true"
        clientAuth="true" sslProtocol="SSL"
        sslOptions="ssl2=true,ssl3=true,tls=true"
       
ssl2Ciphers="-SSL2_RC4_128_WITH_MD5, ..."
       
ssl3Ciphers="-SSL3_FORTEZZA_DMS_WITH_NULL_SHA, ..."
       
tls3Ciphers="-SSL3_FORTEZZA_DMS_WITH_NULL_SHA, ..."
        SSLImplementation="org.apache.tomcat.util.net.jss.JSSImplementation"
        enableOCSP="true"   
        ocspResponderURL="http://server.example.com:9180/ca/ocsp"   
        ocspResponderCertNickname="ocspSigningCert cert-pki-ca 102409a"   
        ocspCacheSize="1000"   
        ocspMinCacheEntryDuration="60"   
        ocspMaxCacheEntryDuration="120"   
        ocspTimeout="10"   
        debug="true"
        serverCertNickFile="/var/lib/pki-kra/conf/serverCertNick.conf"
        passwordFile="/var/lib/pki-kra/conf/password.conf"
        passwordClass="org.apache.tomcat.util.net.jss.PlainPasswordFile"
        certdbDir="/var/lib/pki-kra/alias"/>
```
If the given OCSP service is not the CA, then the OCSP service's signing certificate must be imported into the subsystem's NSS database. This can be done in the console or using certutil; both options are covered in Section 15.6.1, “Installing Certificates in the Certificate System Database”.
Restart the subsystem. For example:
```
service pki-kra restart
```

⁠

Table 6.2. OCSP Parameters for server.xml

Parameter	Description
enableOCSP	Enables (or disables) OCSP checking for the subsystem.
ocspResponderURL	Sets the URL where the OCSP requests are sent. For an OCSP Manager, this can be its own internal service or another OCSP service in another OCSP or in a CA. For a TKS or DRM, this always points to an external OCSP service in an OCSP or a CA.
ocspResponderCertNickname	Sets the nickname of the signing certificate for the responder, either the OCSP signing certificate or the CA's OCSP signing certificate. The certificate must be imported into the subsystem's NSS database and have the appropriate trust settings set.
ocspCacheSize	Sets the maximum number of cache entries.
ocspMinCacheEntryDuration	Sets minimum seconds before another fetch attempt can be made. For example, if this is set to 120, then the validity of a certificate cannot be checked again until at least 2 minutes after the lest validity check.
ocspMaxCacheEntryDuration	Sets the maximum number of seconds to wait before making the next fetch attempt. This prevents having too large a window between validity checks.
ocspTimeout	Sets the timeout period, in seconds, for the OCSP request.

⁠6.5.3. Enabling Revocation Checking for the TPS and RA

The TPS and RA subsystems can be configured to use revocation checking through an OCSP responder, as with the other subsystems. Alternatively, because TPS and RA subsystems use Apache web servers, they can be configured to use CRLs directly, through the mod_revocator module.

Using an OCSP responder is the recommended method.

⁠6.5.3.1. Using an OCSP Responder with mod_nss

Both the TPS and RA subsystems use web-based administrative services, which require administrators and agents to authenticate using SSL client certificates. The TPS also uses certificate-based authentication for officers to access the Enterprise Security Client interfaces.

Because administrative functions depend on having a valid certificate, the validity of the certificate should be checked in both subsystems so that suspended or lost tokens or revoked certificates cannot be used to gain access to the administrative functions of the subsystem.

OCSP checking can be enabled in both the TPS and the RA by setting certain parameters in their nss.conf files. Most of the configuration for enabling OCSP validation is already in the file, but it needs to be uncommented and configured.

NOTE

NSS, part of the Apache web server used by the TPS and the RA, provides the mechanism for contacting the OCSP service. However, NSS caches OCSP responses for 60 minutes. If the TPS or RA polls again for the revocation status of a certificate within an hour of its being checked, NSS returns the cached response, even if the revocation status has changed.

If there is a very important or vulnerable certificate revocation, then it may be beneficial to restart the subsystem to clear its NSS cache so an inaccurate status cannot be returned.

Get the name of the OCSP signing certificate for the OCSP or CA which will be used to check certificate status. For example:

# certutil -L -d /var/lib/pki-ca/alias

Certificate Nickname                                         Trust Attributes
                                                             SSL,S/MIME,JAR/XPI

Certificate Authority - Example Domain                       CT,c,
ocspSigningCert cert-pki-ca CTu,Cu,Cu
subsystemCert cert-pki-ca                                  u,u,u
Server-Cert cert-pki-ca                                    u,u,u
auditSigningCert cert-pki-ca                               u,u,Pu

Update to the latest version of NSS.
```
yum update nss
```
Open the subsystem's nss.conf file. For example:
```
vim /var/lib/pki-tps/conf/nss.conf
```
Enable OCSP checking, and set the information for the OCSP service to use by uncommenting three lines:
```
NSSOCSP on
NSSOCSPDefaultResponder on

NSSOCSPDefaultURL http://ocsp.example.com:11180/ocsp/ocsp
```
IMPORTANT
Make sure that the NSSEnforceValidCerts directive is not set to false. One way to ensure that is to remove the line from the nss.conf file or comment it out.
The TPS and RA can be configured to work with the CA's internal OCSP service or an external OCSP Manager.
Set the certificate to use for authentication for OCSP validation.
If the CA's internal OCSP service is used, then the certificate to use for authentication is the CA's OCSP signing certificate. To use an external OCSP Manager, set the certificate nickname to the OCSP signing certificate nickname for the OCSP Manager. By default, both the CA's OCSP signing certificate and the OCSP Manager's OCSP signing certificate have the nickname of ocspSigningCert instanceName.
For example, using the CA's OCSP signing certificate:
```
NSSOCSPDefaultName "ocspSigningCert cert-pki-ca"
```
Add the OCSP certificate used by the OCSP service to the subsystem's cert8.db database.
The OCSP signing certificate must be imported into the TPS or RA security database:
1. Retrieve the OCSP signing certificate from the end-entities services pages for the CA. The OCSP signing certificate has a subject name such as CN=OCSP Signing Certificate, O=Example Domain.
  Save the base 64-encoded certificate to a file like ocsp.cert.
2. Import the OCSP signing certificate into the subsystem's security database.
```
certutil -A -n "ocspSigningCert cert-pki-ca" -t "C,," -d /var/lib/pki-tps/alias -a -i /path/ocsp.cert
```
  Importing certificates into the security database is described in Section 15.6.1.2, “Installing Certificates Using certutil”.
Configure the OCSP timeout value. The parameter determines how long the TPS waits for a response from the OCSP responder before timing out. The default value (60 seconds) is usually fine, but when there is spotty network performance, it is better to set a higher value to keep the slower transactions from timing out unnecessarily.
```
NSSOCSPTimeout 90
```
If the timeout is not set, there is a default value of 60 seconds.
Configure how the OCSP cache is handled for the TPS. Not setting any cache parameters simply uses the default settings. The cache parameters can be configured to enable more frequent OCSP checks.
The TPS uses the OCSP services provided by the NSS security libraries. The idea of the OCSP cache is to keep a record of recent responses from the OCSP server. If not too much time has passed since a particular validation request has been made to the OCSP server, the cache settings give the TPS the option of getting the validity of the certificate from the value in the cache rather than the server. This flexibility reduces the strain on the OCSP server.
The default values that govern cache behavior are all set to allow a fairly long time between fetches to the OCSP server.
There are three parameters that control caching behavior:
- NSSOCSPCacheSize controls the number of certificate validity requests that can be stored in cache. The default is 1000.
- NSSOCSPMinCacheEntryDuration sets the minimum amount of time (in minutes) that the TPS waits after checking a certificate's status before the certificate status can be re-checked. To increase security, set this time to something small, so that the OCSP responder can be checked as often as possible and catch recently revoked certificates. The default time is one hour.
- NSSOPCSPMaxCacheEntryDuration sets the maximum amount of time before the TPS checks the OCSP responder about a certificate. OCSP responders have an optional setting to configure it's a good time for the client to query the service. The NSSOPCSPMaxCacheEntryDuration attribute overrides the default settings in the OCSP responder and allows you to define whatever window you want. The default setting for this is one day.
For example:
```
NSSOCSPCacheSize 1000
NSSOCSPMinCacheEntryDuration 60
NSSOPCSPMaxCacheEntryDuration 80
```
Restart the subsystem. For example:
```
service pki-tps restart
```

⁠6.5.3.2. Managing CRLs with mod_revocator

The RA and the TPS, which both use Apache for their web services, use mod_revocator to manage their CRLs and enable revocation checking. Using mod_revocator provides a dedicated and reliable way to automate CRL downloads from both HTTP and LDAP sources (over standard or secure connections). The subsystem configuration in the /etc/httpd/conf.d/revocator.conf file defines the settings used by mod_revocator, such as the interval between CRL downloads and the maximum age of a CRL. If a CRL is not available or if it is older than the allowed maximum age, then mod_revocator shuts down the web services so that the subsystem doesn't attempt certificate verification using outdated CRLs.

Open the revocator.conf file.
```
# vim /etc/httpd/conf.d/revocator.conf
```
Set up the CRL parameters. Two parameters are required:
- CRLEngine must be set to on for the Apache instance to retrieve the CRLs.
- CRLFile must point to a URL where the Apache server can find the CRL. There are several different valid formats, including downloading from an LDAP server is LDAP publishing is enabled. A simple configuration is to use the web services page over HTTPS. In this case, the URL has the format http://hostname:port/path[;update_interval;wait_time].
These parameters are explained more in the comments in the revocator.conf file.
For example:
```
CRLEngine on
CRLAgeCheck off
CRLUpdateCritical off
CRLFile "http://ca.example.com:9180/MasterCRL.crl;30;30"
```

mod_revocator is described in more detail on the 389 Project design pages.