Ubuntu Manpage: fetch-crl - retrieve certificate revocation lists

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.

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 '.rn' must be
       removed manually.