mod_revocator


Table of Contents

Introduction
Building
Package Requirements
Configuration Directives
Developer Information

Introduction

This Apache module lets the user configure remote Certificate Revocation Lists (CRLs) to be downloaded and installed automatically on a regular basis without restarting the server. This helps ensure that the CRLs are kept up-to-date with minimal effort. The module can also bring the server down if the CRL expires and a new one cannot be obtained. This module requires that mod_nss also be installed.

Building

Refer to the README file included with the distribution for the latest information.

Package Requirements

To build this you'll need:
mod_revocator will not work with earlier versions of NSS due to an API change.

Option
 Description
--with-apr-config Use apr-config to determine the APR directory
--with-apxs=PATH Path to apxs
--with-nspr=PATH Netscape Portable Runtime (NSPR) directory
--with-nspr-inc=PATH Netscape Portable Runtime (NSPR) include file directory
--with-nspr-lib=PATH Netscape Portable Runtime (NSPR) library directory
--with-nss=PATH Network Security Services (NSS) directory
--with-nss-inc=PATH Network Security Services (NSS) include directory
--with-nss-lib=PATH Network Security Services (NSS) library directory
--with-ldapsdk=PATH LDAP SDK directory
--with-ldapsdk-inc=PATH Mozilla LDAP SDK include directory
--with-ldapsdk-lib=PATH Mozilla LDAP SDK library directory
--enable-openldap
 Use OpenLDAP instead of the  Mozilla LDAP SDK


The --with-nspr, --with-nss and --with-ldapsdk tags require that the package be installed in the same parent directory (e.g. /opt/nspr, /usr/local/nspr, etc). It will look in this parent for include/, lib/, etc. Alternatively you can use -inc and -lib to specify separate locations for each one (--with-nspr-inc, --with-nspr-lib, --with-nss-inc, etc).

If --with-nss or --with-nspr and/or --with-ldapsdk are not passed configure will look for the [nss|nspr|mozldap]-devel packages and use the libraries with that if found.

A sample configure might look something like:

% ./configure --with-apxs[=/path/to/apxs/] --with-nspr=/path/to/nspr/ --with-nss=/path/to/nss/ --with-ldapsdk=/path/to/ldapsdk
% gmake all install

You only need to use =/path/to/apxs if apxs isn't in your path or if you want to install into a specific Apache installation.

This just installs the library librevocation.so. You will need to manually install the Apache module at this point.  A sample configuration file is provided in revocator.conf.

NSPR and NSS are both included with Fedora Core 5 but it doesn't ship the Mozilla LDAP SDK.

Configuration Directives

CRLEngine

This boolean turns on/off CRL revocation. This actives the automatic CRL retrieval for this server.

CRLUpdateCritical

Shut down server if CRL updates fail (for example, if the remote URL is not accessible).

CRLAgeCheck

Boolean that when enabled will shut down server if CRLs are too old. The server will shut down if the age of a downloaded CRL exceeds the time specified in its Next Update field. This condition indicates that the CRL may not contain the most recent information available. To avoid the possibility of users authenticating with compromised certificates that would have been added to an up-to-date CRL, you can choose to have the server shut down automatically when a CRL is considered too old.

This check is performed when the CRL is downloaded. Therefore, an already downloaded CRL can become older than its Next Update time in the interval between updates and still be considered valid. This feature does not apply to CRLs that do not have a Next Update field.

CRLFile

A space-delimited list of protocol://urldata;update_interval;max_age If multiple remote locations are listed then the value will need to be enclosed in double-quotes.

urldata specifies the URL(s) of remote CRLs to retrieve and install. mod_revocator can download CRLs over HTTP, HTTP over SSL, LDAP, and LDAP over SSL. You can also specify a binary executable to retrieve the data. This executable must return the data via stdout. The executable option is primarily to work around LDAP library resolution problem but any executable may be used. For LDAP you may only retrieve one attribute. Valid URL formats are:

For example:

ldap://ldap.example.com:5000/o=example.net?usercertificate%3binary telephoneNumber?sub?(sn=Jensen)??
For example:

https://ca.example.com:1025/getCRL?op=getCRL&issuepoint=MasterCRL
For example:

exec:///opt/fortitude/bin/ldapget|ldap://ldap.example.com:3389/ o=example.com?userCertificate%3bbinary?sub?(uid=crl)??

The ldapget program is supplied to demonstrate how this works and to provide LDAP/S support. The usage for ldapget is:

/path/to/ldapget [/path/to/certdatabase] ldap://...

update_interval specifies the maximum amount of time in minutes to allow between CRL downloads.

At startup, mod_revocator downloads all CRLs configured for automatic downloading. To determine the time of the next download, mod_revocator uses this value or the time specified in the Next Update field of the CRL, whichever is sooner. Not all CRLs have a Next Update field, however, so you must specify an update interval for each CRL.

To determine an appropriate update interval, consider the network connectivity and available bandwidth at your site and how often the CRL is updated. If you it is critcal to have up-to-date revocation information then OCSP is probably a better way to go.

max_age specifies the time in minutes you want mod_revocator to wait past the time indicated in the CRL's Next Update field before determining that the CRL is too old to be valid.

To avoid unnecessary shutdowns it is recommended that you set this value no lower than 5 minutes and take into account possible system time differences between the server host and the CA's CRL download server.

If you have not enabled the option CRLUpdateCritical then the value specified in this field has no impact. A good starting value is 60 minutes.

A sample configuration might look like:

CRLEngine on
CRLFile http://somehost.example.com/MasterCRL.crl;60;60
CRLAgeCheck off
CRLUpdateCritical off

Operation

In order for the CRL to be loaded you need to trust the issuer. This is often issued by a separate certificate on the CA, so you may need to trust multiple certificates. If the CRL is signed by an unknown issuer or is not trusted you will get the error message:

Error updating CRL http://ca.example.com/MasterCRL.crl no subject : Unknown issuer for this CRL

In order to load this CRL you will need to import and trust the CA and/or OCSP signing certificate. Save the certificate(s) into text files and use the NSS certutil command to import it. Note that your nickname (-n) and database path (-d) may differ:

% certutil -A -n "CA" -d /etc/httpd/alias -t CT,, -a -i /path/to/ca.crt

% certutil -A -n "OCSP cert" -d /etc/httpd/alias -t CT,, -a -i /path/to/ocsp.crt

The default Apache LogLevel is warn. This will log basic information about the  module and will report the first successful retrieval of each CRL. Subsequent retrievals are only logged in the LogLevel is set to debug.

An example log is:

Successfully downloaded CRL at URL http://ca.example.com/MasterCRL.crl, subject = CN=Certificate Manager,OU=Engineering,O=Example,C=US, lastupdate = Thu Oct 12 15:39:19 2006, nextupdate = Thu Oct 12 19:39:19 2006
Revocation subsystem initialized

Developer Information

This module uses some internals from NSS. This is normally a big no-no but there was no other way to get around it. As such a private copy of some of the NSS include files can be found in the mozilla subdirectory. If you use a version of NSS other than 3.9.3 then you should replace the files in this directory with appropriate files from whatever version you are using. NSS 3.9.3 introduced a new locking mechanism for PKCS#11 modules. As such the CKFW interface changed slightly so the nsprstub.cpp in this module will not work with previous versions of NSS.