FetchCRL3

New features in version 3.0

• support for multiple output formats: OpenSSL 1 in dual-hash mode, specific DER and PEM outputs (NSS CRL databases are scheduled for release 3.1)
• support for multiple CRLs for a single CA, allowing more than one CA with the same subject name but different CLRs. Review your client software to see if and how these CRLs are used.
• stateful retrieval helps reduce bandwidth usage by caching the CRLs locally and respecting the Cache Control headers sent by the web server hosting the CRL. This can reduce the number of downloads
• support for HEAD-only requests when state preservation is used (initially only retrieve HTTP headers, and only if the CRL actually changed to a full download)
• support for more CRL retrieval protocols (file:// and ftp://)
• ability to try site-local URLs first, before relying on the URLs shipped with the trust anchor. This allows building an explicit local caching (web) server.
• ability to specify additional URLs to try in case the URLs shipped with the trust anchor were not responsive. This allows for automatic fall-back to (local or global) mirror services for CRL downloads
• warnings and errors can be suppressed on a per-trust anchor basis, to allow silencing for particularly unstable trust anchors
• aging tolerance (the delay time before errors are generated in case downloads consistently fail) can be configured on a per-trust anchor basis
• parallel downloading for multiple trust anchors
• minimized use of temporary files in the file system (now limited to the invocation of OpenSSL only, and only for brief periods of time)
• dependencies on wget, lynx and other unix utilities have been removed
• explicit web proxy support (using LWP http proxies)
• completely re-written in perl, with some (hopefully minimal) dependencies: LWP, Sys::Syslog, POSIX. And Data::Dumper (when debugging is enabled), and IO::Select (if parallel downloads are enabled).

Downsides of the new version

• it requires perl5 to be installed (tested with perl 5.8.0) with libwww-perl, whereas version 2 only required a traditional Bourne shell
• requires a version of OpenSSL (0.9.5a or better) to be installed. Needs OpenSSL 1.0.0 (at least beta5) for dual-hash support.
• when using parallel downloads, it can only run on pure-POSIX systems

Configuration options

General section

infodir

directory containing the meta-data (".info") or crl_url files

Default: /etc/grid-security/certificates

cadir

directory containing the trust anchors against which retrieved CLRs will be verified

Default: set to infodir

output

directory where the resulting CRLs will be written, unless a format-specific destination is specified

Default: set to infodir

output_(pem,der,openssl)

format-specific output directory

Default: set to output

statedir

directory where the state-and-cache file for each CRL is kept. If this directory is not set or does not exist, no state is kept. See the section on Stateful retrieval for more information

Default: set to /var/cache/fetch-crl if this directory exists, undefined otherwise

logmode

distination(s) for log messages generated: direct - print message immediately, qualified - print message immediately prefixed with the type of message, cache - save messages and print them all when the log is flushed, and syslog - send messages to syslog at the syslogfacility facility with a severity based on the type of message (NOTICE for warnings, ERR for errors, and DEBUG for verbose and debug messages)

Default: qualified

syslogfacility

facility used by the syslog output driver.

Default: daemon

formats

output formats in which the CRLs will be installed. Comma-separated list of one or more of openssl, der, pem, and/or nss

Default: openssl

openssl

location of the OpenSSL binary to use

Default: openssl (uses path to resolve)

opensslmode

use only the default hash (single) or also the pre-1.0 hash (dual) of the subject name for CRLs written with for use with OpenSSL 1.0 and up. Is only used in base the OpenSSL binary is version 1.0.0 or later.

Default: dual

path

executable search path ($PATH)

Default: unchanged from invocation

randomwait

wait up to x seconds before commencing the retrieval process

Default: unset

httptimeout

maximum time spent in a single HTTP request (HEAD or GET) in seconds

Default: 120

http_proxy

HTTP proxy URL, or the token "ENV" - in which case the environment variable settings for the perl LWP library are used

Default: unset

catemplate

list of filename templates to 'guess' the name of the trust anchor (certificate) file in the cadir belonging to a particular CRL

Default: @ALIAS@.pem; @ALIAS@.@R@; @ANCHORNAME@.@R@

nametemplate_der

template of the name of the CRL file for the DER output writer

Default: @ANCHORNAME@.@R@.crl

nametemplate_pem

template of the name of the CRL file for the PEM output writer

Default: @ANCHORNAME@.@R@.crl.pem

prepend_url

list of URL templates to be tried first, before the crl_url list in the trust anchor metadata (or the lines in the crl_url file) are attempted. The "@ALIAS@", "@ANCHORNAME@", and "@R@" tokens are expanded for each trust anchor CRL.

Default: unset

postpend_url

list of URL templates to be tried in all other URLs failed,after the crl_url list in the trust anchor metadata (or the lines in the crl_url file) have been attempted. The "@ALIAS@", "@ANCHORNAME@", and "@R@" tokens are expanded for each trust anchor CRL.

Default: unset

(no)warnings

disable or enable warning messages

Default: warnings enabled

(no)errors

disable or enable error messages

Default: error messages enabled

(no)backups

(do not) make backups of the trust anchor files when written (but does not apply to NSS databases).

Default: no backups

stateless

do not use from nor write in a state directory to manage historic data, even if a state directory is present

Default: will use state directory if it exists

version

set the fetch-crl version number, e.g., used in the User-Agent header for HTTP requests.

Default: 3.0

packager

override the packager of this distribution

Default: EUGridPMA

Trust Anchor sections

A trust anchor section must be named after the 'alias' of the trust anchor. In case a .info meta-data file is used, the alias is defined in this meta-data file. In case a crl_url file is used to load the URLs, the alias will be set to the basename of the crl_url file, without the ".crl_url" suffix.

crl_url.i

override the list of CRL download URLs for this trust anchor by the URL(s) given in this list. The list of URLs is on a single line, with URLs separated by semi-colons (";").

agingtolerance, httptimeout, nametemplate_der, nametemplate_pem, cadir, catemplate, statedir

override the global defaults for this trust anchor. This override takes precendence overglobal configuration settings as well as over command-line supplied settings!

(no)prepend_url, (no)postpend_url, (no)warnings, (no)errors, (no)http_proxy

override global default, with options that are revertible, so "nopostpend_url" will prevent the default postpend_url from being used for this trust anchor. "nohttp_proxy" will prevents the HTTP proxy from being used to download CRLs for this trust anchor.

proctimeout

override the over-all timeout for the duration of the CRLs installation process for this trust anchor.

As always, the "@R@", "@ALIAS", and "@ANCHORNAME@" tokens are expended in URLs.

Example

# configuration file fetch-crl3
# use SEMICOLON (;) or \001 (^A) as list separators in values
#
infodir = /etc/grid-security/certificates
statedir = /var/cache/fetch-crl
formats = openssl, pem
output_pem = /etc/pki/tls/certs
nametemplate_pem = @ALIAS@.r@R@.pem
opensslmode = single
randomwait = 30
httptimeout = 30
nowarnings
prepend_url = file:///share/grid-security/certificates/@ANCHORNAME@.r@R@
postpend_url = http://dist.eugridpma.info/certificates/@ANCHORNAME@.r@R@
openssl = /global/ices/toolset/arch/i686-pc-linux-gnu/openssl-1.0.0a/bin/openssl
path = /bin:/usr/bin:/usr/ucb
nobackups

[EDG-Tutorial-CA]
agingtolerance = 168
noerrors
nowarnings
nopostpend_url
crl_url.1 = file:///usr/local/etc/extracrl.pem

which will

• actually write two (2!) copies of each downloaded CRL: one in /etc/grid-security/certificates/hash.ri, and another copy in /etc/pki/tls/certs/alias.ri.pem
• try to retrieve the CRL first from a local file (e.g. NFS or AFS mounted), then from the URLs contained in the trust anchor store, and if all else fails goes to the EUGridPMA web page to get the last copy of the CRL cached there (assuming the ANCHORNAME is the OpenSSL0 hash)
• for the EDG Tutorial CA, the postpend_url emergency is removed, since this CA is not with the IGTF anyway and there is no cache at the EUGridPMA site for it.

Known issues

• although fetch-crl3 will install multiple CRLs in the CRl stores (called ".r0", ".r1", or labelled appropriately in an NSS store), if the number of CRLs decreases the left-overs are not automatically removed. So if the number of CRLs for a particular CA does down from n to n-1, the file ".rn" must be removed manually.
• NSS CRL database support is currently not implemented
• Overall process fimeouts (proctimeout) is currently not implemented