FetchCRL3

From PDP/Grid Wiki
Jump to navigationJump to search

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
parallelism
number of parallel processes used to retrieve trust anchor CRLs. The parallelism is on a per-trust anchor basis (so multiple CRLs for the same trust ancnhor will be retrieved by the same sub-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' or 'anchorname' (filename) 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. In case the alias is different from the anchorname, both will be used for section lookup, with a section for the alias taking precedence over the section for the anchorname.

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.

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