August 3, 2006 mod_revocator is open sourced
October 17, 2006 mod_revocator 1.0.2 is tagged
- Fix a slew of compilation warnings
- Fix Makefile so it can be built in parallel (make -j 3)
- Add support for OpenLDAP as the LDAP library
- Improve the documentation
April 13, 2010 mod_revocator 1.0.3 is tagged
- Fix to work with new mod_nss forking model (initialization done in child rather than parent)
- Move CRL fetching into an external program so every child doesn't each need to download the CRLs
What is mod_revocator?
mod_revocator is an Apache module that lets an administrator 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.
mod_revocator uses the Apache Version 2.0 License.
What features does mod_revocator provide?
- Automatic CRL download and installation from an HTTP[S] or LDAP[S] source
- The source can be an executable that retrieves the CRL from another method
- Can specify per CRL source the interval between downloads
- Can specify per CRL source the maximum age of the CRL before requiring a new one
- Can shut down the server if a CRL is not available
What platforms does it support?
mod_revocator has only been tested on Red Hat Enterprise Linux 5, Fedora 9+. It may work on other platforms but it is untested. It should work with any platform that supports Apache and NSS/NSPR. I doubt that it will work in a Win32 environment. It has worked in the past on Solaris but has not been tested on that platform recently.
It has been tested against 2.0.52 (RHEL 4), 2.0.54 and 2.2.0
On Solaris it was tested using Apache 2.0.52.
mod_revocator Patches Compatibility Matrix
|RHEL 5||RHEL 6||Fedora 18||Fedora 19||RHEL 7|
- DOWNSTREAM PATCH EXISTS UPSTREAM
|where||DOWNSTREAM||=||RHEL 5 and RHEL 6, and|
|UPSTREAM||=||Fedora 18, Fedora 19, and RHEL 7|
What do I need to run mod_revocator?
Where can I get a binary?
Binaries are not available yet.
What can I get the source?
You can download the source for mod_revocator from cvs.fedora.redhat.com. To check out the source anonymously use
CVSROOT=:pserver:firstname.lastname@example.org:/cvs/dirsec ; export CVSROOT cvs login
(password is empty i.e. just press Enter or Return)
If you have commit access, use
CVSROOT=:ext:email@example.com:/cvs/dirsec ; export CVSROOT
You will have to apply for commit access - see our contributing page on more information on how to get CVS commit access.
Now you're ready to pull the source:
cvs -z3 co -r RELEASETAG mod_revocator
The current tag is mod_revocator103
A tarball is available at http://directory.fedoraproject.org/sources/mod_revocator-1.0.3.tar.gz
How do I build it?
Refer to the README included in the distribution. In short you need the NSPR, NSS and LDAP SDK libraries, the Apache developer kit (apxs and the include headers) and a compiler. We've tested with gcc 3.x and Forte C v6.2 and 11.
You need to pass in the location of NSPR and NSS and if you are using your own build of Apache (as opposed to the system installed one) the path to apxs. The arguments are:
--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 LDAP SDK include directory --with-ldapsdk-lib=PATH LDAP SDK library directory --enable-openldap Use OpenLDAP as the LDAP library (default=no)
The multiple options for NSS, NSPR, LDAP SDK are due to the two possible situations. You can have the include and library files under a single directory, say /components/nss/lib and /components/nss/include or you can have them installed in discrete directorys, say /usr/include/nss3 and /usr/lib/nss3. If you have them together you can use --with-nss. If you have them in separate locations, use --with-nss-inc and --with-nss-lib. You will likely use the later.
There is a make install target but it only installs a shared library. You will need to manually install the Apache module (mod_revocator.so) and it's configuration file.
Fedora includes NSPR and NSS. You'll need the following packages:
CRLEngine (on/off). This turns on/off CRL revocation. This actives the automatic CRL retrieval for this server.
CRLUpdateCritical (on/off). Shut down server if CRL updates fail.
CRLAgeCheck (on/off). 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. This 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:
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.
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 config in httpd.conf might look like:
CRLEngine on CRLFile http://somehost.example.com/MasterCRL.crl;60;60 CRLAgeCheck off CRLUpdateCritical off
Apache tends to be linked against openldap. mod_revocator is linked against the Mozilla LDAP SDK so while the API's are generally the same the data structures are very different. So LDAP URLs aren't working in mod_revocator yet. The solution thus far is to use the exec URL format and something like ldapget that can be linked against the Mozilla LDAPSDK.
How it Works
Defining a CRL to retrieve
You define the CRL sites to download from in the Apache configuration. Each entry includes:
- The URL to fetch the file from
- The time period between fetches
- The maximum age of the CRL
So for example, http://somehost.example.com/MasterCRL.crl;60;60
- The CRL is located at http://somehost.example.com/MasterCRL.crl
- The server will wait 60 minutes or the difference between the current time and nextUpdate. The nextUpdate time takes priority
- The CRL can be no more than 60 minutes past the nextUpdate time (if set) or the time it was last retrieved. This field is only meaningful if CRLAgeCheck is on.
When CRLs are retrieved and installed
Upon server startup all CRLs are retrieved.
After that, a CRL is retrieved if:
- It has been at least a minute since the last update
- the current time is past the next update time in the CRL (if one)
- the difference between the last time the CRL was retrieved and the current time is greater than the refresh period defined for the URL
Otherwise the module sleeps the difference in time of the current time minus nextupdate or refresh (basically, sleep until we need to get it again).
When a CRL is retrieved, if CRLAgeCheck is enabled in the Apache configuration and maximum age is > 0:
If the CRL has a next update date it is compared to the current time.
If it is older than the current time AND the difference in the current time versus the next update is greater than the maximum age the server is shut down.
The module then goes back to sleep until the next retrieval time.
What happens when a CRL is unavailable
If a CRL cannot be retrieved (it isn't there, the network is down, etc.) AND CRLUpdateCritical is enabled in the Apache configuration then the server is shut down.
If CRLUpdateCritical is not set then the server will try again in 60 seconds and will keep retrying. If CRLAgeCheck is not set then it will continue to try and fail infinitely. If CRLAgeCheck is set then after that time has passed the server will be shut down.