[Fedora-directory-commits] mod_revocator/docs mod_revocator.html, NONE, 1.1

Tue Sep 5 19:58:29 UTC 2006

Author: rcritten

Update of /cvs/dirsec/mod_revocator/docs
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv29154

Added Files:
	mod_revocator.html 
Log Message:
HTML documentation for mod_revocator

--- NEW FILE mod_revocator.html ---
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<!--
 Copyright (c) 2006 Red Hat, Inc. All rights reserved.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
-->
  <meta content="text/html; charset=ISO-8859-1"
 http-equiv="content-type">
  <title>mod_revocator</title>
</head>
<body>
<h1 style="text-align: center;">mod_revocator</h1>
<br>
<h2>Table of Contents</h2>
<a href="#Introduction">Introduction</a><br>
<a href="#Building">Building</a><br>
<div style="margin-left: 40px;"><a href="#Package_Requirements">Package
Requirements</a><br>
</div>
<a href="#Configuration_Directives">Configuration Directives</a><br>
<a href="#Developer_Information">Developer Information </a><br>
<h1><a name="Introduction"></a>Introduction</h1>
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 <a
 href="http://directory.fedora.redhat.com/wiki/Mod_nss">mod_nss</a>
also be installed.
<br>
<h1><a name="Building"></a>Building </h1>
Refer to the README file included with the distribution for the latest
information.<br>
<h2><a name="Package_Requirements"></a>Package Requirements<br>
</h2>
To build this you'll need:<br>
<ul>
  <li><a href="http://www.mozilla.org/projects/nspr/">NSPR</a> 4.4.1 or
higher<br>
  </li>
  <li><a href="http://www.mozilla.org/projects/security/pki/nss/">NSS</a>
3.9.3 or higher<br>
  </li>
  <li>Mozilla <a href="http://www.mozilla.org/directory/csdk.html">LDAP
SDK</a> 5.15 or higher</li>
  <li>Apache development package(s)</li>
  <li><a href="http://directory.fedora.redhat.com/wiki/Mod_nss">mod_nss</a><br>
  </li>
</ul>
mod_revocator will not work with earlier versions of NSS due to an API
change. <br>
<br>
<table style="width: 70%;" border="0" cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top; font-weight: bold;">Option<br>
      </td>
      <td style="vertical-align: top; font-weight: bold;">Description<br>
      </td>
    </tr>
    <tr>
      <td>--with-apr-config</td>
      <td>Use apr-config to determine the APR directory</td>
    </tr>
    <tr>
      <td>--with-apxs=PATH</td>
      <td>Path to apxs</td>
    </tr>
    <tr>
      <td>--with-nspr=PATH</td>
      <td>Netscape Portable Runtime (NSPR) directory</td>
    </tr>
    <tr>
      <td>--with-nspr-inc=PATH</td>
      <td>Netscape Portable Runtime (NSPR) include file directory</td>
    </tr>
    <tr>
      <td>--with-nspr-lib=PATH</td>
      <td>Netscape Portable Runtime (NSPR) library directory</td>
    </tr>
    <tr>
      <td>--with-nss=PATH</td>
      <td>Network Security Services (NSS) directory</td>
    </tr>
    <tr>
      <td>--with-nss-inc=PATH</td>
      <td>Network Security Services (NSS) include directory</td>
    </tr>
    <tr>
      <td>--with-nss-lib=PATH</td>
      <td>Network Security Services (NSS) library directory</td>
    </tr>
    <tr>
      <td>--with-ldapsdk=PATH</td>
      <td>LDAP SDK directory</td>
    </tr>
    <tr>
      <td>--with-ldapsdk-inc=PATH</td>
      <td>Mozilla LDAP SDK include directory</td>
    </tr>
    <tr>
      <td>--with-ldapsdk-lib=PATH</td>
      <td>Mozilla LDAP SDK library directory</td>
    </tr>
  </tbody>
</table>
<br>
<br>
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). <br>
<br>
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.<br>
<br>
A sample configure might look something like: <br>
<br>
<code>% ./configure --with-apxs[=/path/to/apxs/]
--with-nspr=/path/to/nspr/ --with-nss=/path/to/nss/
--with-ldapsdk=/path/to/ldapsdk <br>
% gmake all install <br>
</code><br>
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. <br>
<br>
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. <br>
<br>
NSPR and NSS are both included with Fedora Core 5 but it doesn't ship
the Mozilla LDAP SDK.
<br>
<h1><a name="Configuration_Directives"></a>Configuration Directives</h1>
<big><big>CRLEngine</big></big><br>
<br>
This boolean turns on/off CRL revocation. This actives the automatic
CRL retrieval for this server. <br>
<br>
<big><big>CRLUpdateCritical</big></big><br>
<br>
Shut down server if CRL updates fail (for example, if the remote URL is
not accessible).<br>
<br>
<big><big>CRLAgeCheck</big></big><br>
<br>
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. <br>
<br>
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. <br>
<br>
<big><big>CRLFile</big></big><br>
<br>
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. <br>
<br>
<span style="font-weight: bold;">urldata</span> 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: <br>
<br>
<ul>
  <li>ldap[s]://hostname:port/base_dn?attributes?scope?filter </li>
</ul>
<div style="margin-left: 40px;">For example: <br>
</div>
<br>
<div style="margin-left: 40px;">ldap://ldap.example.com:5000/o=example.net?usercertificate%3binary
telephoneNumber?sub?(sn=Jensen)?? <br>
</div>
<ul>
  <li>http[s]://username:password at hostname:port/path[?query_string] </li>
</ul>
<div style="margin-left: 40px;">For example: <br>
<br>
https://ca.example.com:1025/getCRL?op=getCRL&issuepoint=MasterCRL <br>
</div>
<ul>
  <li>exec://path/to/program|argument1|...|argumentn </li>
</ul>
<div style="margin-left: 40px;">For example: <br>
<br>
exec:///opt/fortitude/bin/ldapget|ldap://ldap.example.com:3389/
o=example.com?userCertificate%3bbinary?sub?(uid=crl)?? <br>
<br>
The ldapget program is supplied to demonstrate how this works and to
provide LDAP/S support. The usage for ldapget is: <br>
<br>
/path/to/ldapget [/path/to/certdatabase] ldap://... <br>
</div>
<br>
<span style="font-weight: bold;">update_interval</span> specifies the
maximum amount of time in minutes to allow between CRL downloads. <br>
<br>
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. <br>
<br>
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.<br>
<br>
<span style="font-weight: bold;">max_age</span> 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. <br>
<br>
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. <br>
<br>
If you have not enabled the option <code>CRLUpdateCritical</code> then
the value specified in this field has no impact. A good starting value
is 60 minutes. <br>
<br>
A sample configuration might look like: <br>
<br>
<div style="margin-left: 40px;"><code>CRLEngine on </code><br>
<code>CRLFile http://somehost.example.com/MasterCRL.crl;60;60 </code><br>
<code>CRLAgeCheck off </code><br>
<code>CRLUpdateCritical off
</code><br>
</div>
<h1><a name="Developer_Information"></a>Developer Information </h1>
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.
<br>
</body>
</html>