NAME¶
fetch-crl - retrieve certificate revocation lists
SYNOPSIS¶
fetch-crl [
-c config] [
-v[
v..
]]
[
-q] [
-h] [
--inet6glue] [
-l infopath]
[
-o outputpath] [
-s statepath]
[
-a agingtolerance] [
-T httptimeout]
[
-r randomwait] [
-p parallelism]
[
--formats openssl|
pem|
der|
nss] ..
[
--define key=
value] ..
[
--cfgdir dirname]
DESCRIPTION¶
The
fetch-crl utility will retrieve certificate revocation lists (CRLs)
for a set of installed trust anchors, based on crl_url files or IGTF-style
info files. It will install these for use with OpenSSL, NSS or third-party
tools.
It works based on a list of trust anchors, for each of which one or more CRLs
should be installed in a CRL store. And for each of these CRLs, one or more
URLs can be specified from which the specific CRL can be retrieved. There are
several supported formats for CRL stores:
- openssl
- has a directory in which hash. i files are stored, one CRL
per file, and all CRLs for the trust anchors whose subject distinguished
name hashes to hash are read and evaluated for each certificate
issues by the CAs whose subject name hash matches hash
OpenSSL in version 1 changes its subject name hashing algorithm, though, so
that for one trust anchor two hashes could be used, depending on
the specific OpenSSL version at hand. If OpenSSL version 1 or higher is
used by fetch-crl and the default mode is used, each CRL is written
out twice, once for each possible hash value. This mode in controlled by
the opensslmode = { dual | single } configuration
option in the configuration file.
- pem
- writes out the CRL in PEM (RFC 1421) format.
- der
- writes out the CRL in binary under distinguished encoding rules
- nss
- will use the crlutil from the Mozilla NSS tools to add or replace a CRL in
the NSS cert8.db database.
Each CRLs can be retrieved from one of several URLs. These URLs are listed by
default in the trust anchor meta-data: the
.info file or the
.crl_url file, as shipped with the trust anchor. In the crl_url file,
there is one URL per line; in the .info file, the
crl_url attribute is
a semi-colon separated list of URLs. These URLs are then tried in order to
retrieve a fresh CRL. Once data has been successfully retrieved, this data is
used as the CRL if it passes verification, signature checking and expiration
checks. Http, https, ftp and file URLs are supported. If data for a CRL has
been downloaded but this data fails any of the subsequent checks (signature
validation, freshness), the CRL data is discarded and NO further URLs are
tried for this CRL!
URLs can be pre-pended or post-pended to the default list via the configuration
file. This can be used to prefer a local mirror repository over any URLs
shipped by the trust anchor provider, without the need to modify the trust
anchor metadata. By post-pending a URL, a 'last-resort' download location can
be added in case the CA provided URLs cannot be used. The pre- and post-pended
URLS are subject to token expansion of the tokens
@ALIAS@,
@ANCHORNAME@, and
@R@, where
R is the sequence number of
the CRL on a per-trust anchor basis.
Retrieved CRLs may be PEM (RFC1421) or DER encoded. They are automatically
converted as needed by fetch-crl, using the OpenSSL command-line tool.
Retrieving a CRL without having an accompanying CA root certificate in an
OpenSSL-accessible form (like
@ALIAS@.0 or
@ANCHORNAME@.@R@ will
result in a verification failures. The CA lookup directory and patterns can be
configured via the configuration file
TOKEN EXPANSION¶
In paths and name templates, tokens are expanded to allow a single pattern to be
used for all trust anchors. The
nametemplate_*,
catemplate,
prepend_url, and
postpend_url configuration settings are subject
to token expansion.
The following tokens are recognised
- @ALIAS@
- The alias name of the trust anchor as defined in the info file. If
there is no info file and the meta-data is retrieved from crl_url
files, then the alias is set to the basename (excluding the .crl_url
suffix) of the filename of the trust anchor.
- @ANCHORNAME@
- The file name of the trust anchor, without any .info or .url_crl
suffix.
- @R@
- The CRL sequence number, counting from 0. Note that most trust anchors
only have a single CRL, with sequence number "0".
OPTIONS¶
- -h --help
- Show help text.
- -l --infodir metadata-directory
- The script will search this directory for files with the suffix '.info' or
'.crl_url'. Note: the CRL files to download must be in either PEM or DER
format.
- -o --out outputDirectory
- Directory where to put the downloaded and processed CRLs. The directory to
be used as argument for this option is typically
/etc/grid-security/certificates Default: infodir (meta-data directory)
- -a --agingtolerance hours
- The maximum age of the locally downloaded CRL before download failures
trigger actual error messages. This error message suppression mechanism
only works if the CRL has been downloaded at least once and either the
crl_url files are named after the hash of the CRL issuer name, or a state
directory is used to preserve state across invocations.
Default: 24 hour aging tolerance
- -q --quiet
- Quiet mode (do not print information messages)
- -r --randomwait s
- Wait up to s seconds before starting the retrieval process(es).
- -p --parallelism n
- Do the retrieval for several trust anchors in parallel, with up to
n processes doing retrievals. At most n downloads will be
active at any one time. Multiple CRLs for the same trust anchor are still
downloaded sequentially.
- --inet6glue
- Load the Net::INET6Glue module to enable IPv6 support in LWP.
- --define key=value
- Add definitions to the configuration at runtime. The key=value pair is
appended to the main section of the configuration, unless a colon is used
in the key: then the part before the colon is the config file section
name, and the part thereafter the key inside that section. To merely set a
valueless option, set to to the null-string "".
CONFIGURATION¶
See
http://wiki.nikhef.nl/grid/FetchCRL3 or the included example file for
a description of the configuration options. The default location of the
configuration file is
/etc/fetch-crl.conf. Supplementary configuration
is read from all files located in
/etc/fetch-crl.d/, or the directory
designated by the
cfgdir directive, whose collated contents are added
to the existing configuration data.
NOTES¶
Defaults can be set in the fetch-crl system configuration file
/etc/fetch-crl.conf.
SEE ALSO¶
openssl(1),
http://wiki.nikhef.nl/grid/FetchCRL3
DIAGNOSTICS¶
Exit status is normally 0; if an error occurs, exit status is 1 and diagnostics
will be written to standard error.
LICENSE¶
Licensed under the Apache License, Version 2.0 (the "License");
http://www.apache.org/licenses/LICENSE-2.0
BUGS¶
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
'.r
n' must be removed manually.