LICENSE

Copyright (c) 2006  Red Hat, Inc. All rights reserved.

This copyrighted material is made available to anyone wishing to use,
modify, copy, or redistribute it subject to the terms and conditions of
the Apache License, 2.0.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY expressed or implied, including the implied warranties of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  A copy of this
license is available at http://www.opensource.org/licenses.  Any Red Hat
trademarks that are incorporated in the source code or documentation are
not subject to the Apache License, 2.0 and may only be used or replicated
with the express permission of Red Hat, Inc.

Red Hat Author(s): Rob Crittenden

SYNOPSIS

 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

 To build this you'll need NSPR 4.4.1 and NSS 3.9.3. Either the Mozilla LDAP
 SDK 5.15 or higher or OpenLDAP 2.2.29 or higher is also required. It will
 not work with earlier versions of NSS due to an API change.
 
 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 are not passed configure will look for the
 mozilla-[nss|nspr]-devel packages and use the libraries with that if found.
 It is strongly recommended that the mozilla.org version be used instead.

 To use OpenLDAP pass in --enable-openldap and do not use any of the
 --with-ldap* directives. It assumes that the OpenLDAP headers are in
 /usr/include and the libraries are resolvable by the loader without
 passing -L.

 Build and install those packages somewhere then configure the module with
 something like:

 % ./configure --with-apxs[=/path/to/apxs/] --with-nspr=/path/to/nspr/ --with-ns
s=/path/to/nss/ --with-ldapsd=/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 the NSS that ships
 lacks libnssb.a so it is not possible to build against that. FC5 also
 doesn't ship the Mozilla LDAP SDK.

 IMPORTANT: This is not at all well-tested against mozldap. Chances are
            very good that it no longer works.

CONFIGURATION

 CRLHelper (/path/to/crlhelper). The full path to the crlhelper program
 which does the actual downloading of remote CRLs.

 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:

    * ldap[s]://hostname:port/base_dn?attributes?scope?filter

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

    * http[s]://username:password@hostname:port/path[?query_string]

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

    * exec://path/to/program|argument1|...|argumentn

      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.

  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
    CRLHelper /usr/bin/crlhelper

DEVELOPERS

  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.

LIBRARIES 

  mod_nss can be retreved from http://directory.fedora.redhat.com/wiki/Mod_nss
  NSS is available at http://www.mozilla.org/projects/security/pki/nss/
  NSPR is available at http://www.mozilla.org/projects/nspr/
  LDAPSDK is available at http://www.mozilla.org/directory/csdk.html