Provided by: fetch-crl_3.0.20-1_all bug

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