1FETCH-CRL(8) System Manager's Manual FETCH-CRL(8)
2
6 fetch-crl - retrieve certificate revocation lists
7
9 fetch-crl [-c config] [-v[v..]] [-q] [-h] [--inet6glue] [-l infopath] [-o out‐
10 putpath] [-s statepath] [-a agingtolerance] [-T httptimeout] [-r randomwait]
11 [-p parallelism] [--formats openssl|pem|der|nss] .. [--define key=value] ..
12 [--cfgdir dirname]
13
15 The fetch-crl utility will retrieve certificate revocation lists (CRLs)
16 for a set of installed trust anchors, based on crl_url files or IGTF-
17 style info files. It will install these for use with OpenSSL, NSS or
18 third-party tools.
19 It works based on a list of trust anchors, for each of which one or
21 more CRLs should be installed in a CRL store. And for each of these
22 CRLs, one or more URLs can be specified from which the specific CRL can
23 be retrieved. There are several supported formats for CRL stores:
24 openssl
26 has a directory in which hash. i files are stored, one CRL per
27 file, and all CRLs for the trust anchors whose subject distin‐
28 guished name hashes to hash are read and evaluated for each cer‐
29 tificate issues by the CAs whose subject name hash matches hash
30 OpenSSL in version 1 changes its subject name hashing algorithm,
32 though, so that for one trust anchor two hashes could be used,
33 depending on the specific OpenSSL version at hand. If OpenSSL
34 version 1 or higher is used by fetch-crl and the default mode is
35 used, each CRL is written out twice, once for each possible hash
36 value. This mode in controlled by the opensslmode = { dual |
37 single } configuration option in the configuration file.
38 pem writes out the CRL in PEM (RFC 1421) format.
40 der writes out the CRL in binary under distinguished encoding rules
42 nss will use the crlutil from the Mozilla NSS tools to add or
44 replace a CRL in the NSS cert8.db database.
45 Each CRLs can be retrieved from one of several URLs. These URLs are
48 listed by default in the trust anchor meta-data: the .info file or the
49 .crl_url file, as shipped with the trust anchor. In the crl_url file,
50 there is one URL per line; in the .info file, the crl_url attribute is
51 a semi-colon separated list of URLs. These URLs are then tried in order
52 to retrieve a fresh CRL. Once data has been successfully retrieved,
53 this data is used as the CRL if it passes verification, signature
54 checking and expiration checks. Http, https, ftp and file URLs are sup‐
55 ported. If data for a CRL has been downloaded but this data fails any
56 of the subsequent checks (signature validation, freshness), the CRL
57 data is discarded and NO further URLs are tried for this CRL!
58 URLs can be pre-pended or post-pended to the default list via the con‐
60 figuration file. This can be used to prefer a local mirror repository
61 over any URLs shipped by the trust anchor provider, without the need to
62 modify the trust anchor metadata. By post-pending a URL, a 'last-
63 resort' download location can be added in case the CA provided URLs
64 cannot be used. The pre- and post-pended URLS are subject to token
65 expansion of the tokens @ALIAS@, @ANCHORNAME@, and @R@, where R is the
66 sequence number of the CRL on a per-trust anchor basis.
67 Retrieved CRLs may be PEM (RFC1421) or DER encoded. They are automati‐
69 cally converted as needed by fetch-crl, using the OpenSSL command-line
70 tool.
71 Retrieving a CRL without having an accompanying CA root certificate in
73 an OpenSSL-accessible form (like @ALIAS@.0 or @ANCHORNAME@.@R@ will
74 result in a verification failures. The CA lookup directory and patterns
75 can be configured via the configuration file
76
79 In paths and name templates, tokens are expanded to allow a single pat‐
80 tern to be used for all trust anchors. The nametemplate_*, catemplate,
81 prepend_url, and postpend_url configuration settings are subject to
82 token expansion.
83 The following tokens are recognised
85 @ALIAS@
87 The alias name of the trust anchor as defined in the info file.
88 If there is no info file and the meta-data is retrieved from
89 crl_url files, then the alias is set to the basename (excluding
90 the .crl_url suffix) of the filename of the trust anchor.
91 @ANCHORNAME@
93 The file name of the trust anchor, without any .info or .url_crl
94 suffix.
95 @R@ The CRL sequence number, counting from 0. Note that most trust
97 anchors only have a single CRL, with sequence number "0".
98
101 -h --help
102 Show help text.
103 -l --infodir metadata-directory
105 The script will search this directory for files with the suffix
106 '.info' or '.crl_url'. Note: the CRL files to download must be
107 in either PEM or DER format.
108 -o --out outputDirectory
111 Directory where to put the downloaded and processed CRLs. The
112 directory to be used as argument for this option is typically
113 /etc/grid-security/certificates Default: infodir (meta-data
114 directory)
115 -a --agingtolerance hours
118 The maximum age of the locally downloaded CRL before download
119 failures trigger actual error messages. This error message sup‐
120 pression mechanism only works if the CRL has been downloaded at
121 least once and either the crl_url files are named after the hash
122 of the CRL issuer name, or a state directory is used to preserve
123 state across invocations.
124 Default: 24 hour aging tolerance
126 -q --quiet
128 Quiet mode (do not print information messages)
129 -r --randomwait s
132 Wait up to s seconds before starting the retrieval process(es).
133 -p --parallelism n
136 Do the retrieval for several trust anchors in parallel, with up
137 to n processes doing retrievals. At most n downloads will be
138 active at any one time. Multiple CRLs for the same trust anchor
139 are still downloaded sequentially.
140 --inet6glue
142 Load the Net::INET6Glue module to enable IPv6 support in LWP.
143 --define key=value
145 Add definitions to the configuration at runtime. The key=value
146 pair is appended to the main section of the configuration,
147 unless a colon is used in the key: then the part before the
148 colon is the config file section name, and the part thereafter
149 the key inside that section. To merely set a valueless option,
150 set to to the null-string "".
151
153 See http://wiki.nikhef.nl/grid/FetchCRL3 or the included example file
154 for a description of the configuration options. The default location of
155 the configuration file is /etc/fetch-crl.conf. Supplementary configu‐
156 ration is read from all files located in /etc/fetch-crl.d/, or the
157 directory designated by the cfgdir directive, whose collated contents
158 are added to the existing configuration data.
159
162 Defaults can be set in the fetch-crl system configuration file
163 /etc/fetch-crl.conf.
164
167 openssl(1), http://wiki.nikhef.nl/grid/FetchCRL3
168
171 Exit status is normally 0; if an error occurs, exit status is 1 and
172 diagnostics will be written to standard error.
173
176 Licensed under the Apache License, Version 2.0 (the "License");
177 http://www.apache.org/licenses/LICENSE-2.0
179
182 Although fetch-crl3 will install multiple CRLs in the CRL stores
183 (called '.r0', '.r1', or labelled appropriately in an NSS store), if
184 the number of CRLs decreases the left-overs are not automatically
185 removed. So if the number of CRLs for a particular CA does down from n
186 to n-1, the file '.rn' must be removed manually.
187Trust Anchor Utilities local FETCH-CRL(8)