Provided by: fetch-crl_3.0.17-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.