1 |
.\" "@(#)$Id: fetch-crl.8,v 1.6 2009/09/21 20:22:32 pmacvsdg Exp $" |
2 |
.\" |
3 |
.\" |
4 |
.PU |
5 |
.TH FETCH-CRL 8 local "Trust Anchor Utilities" |
6 |
.SH NAME |
7 |
fetch-crl \- retrieve certificate revocation lists |
8 |
.SH SYNOPSIS |
9 |
.ll +8 |
10 |
.B fetch-crl |
11 |
.RB [ \-c\ config ] |
12 |
.RB [ \-v [ v .. ] ] |
13 |
.RB [ \-q ] |
14 |
.RB [ \-h ] |
15 |
.RB [ \-l\ infopath ] |
16 |
.RB [ \-o\ outputpath ] |
17 |
.RB [ \-s\ statepath ] |
18 |
.RB [ \-a\ agingtolerance ] |
19 |
.RB [ \-T\ httptimeout ] |
20 |
.RB [ \-r\ randomwait ] |
21 |
.RB [ \-p\ parallelism ] |
22 |
.RB [ \-\-formats\ openssl | pem | der | nss ]\ .. |
23 |
.ll -8 |
24 |
.SH DESCRIPTION |
25 |
The |
26 |
.I fetch-crl |
27 |
utility will retrieve certificate revocation lists (CRLs) for a set of |
28 |
installed trust anchors, based on crl_url files or IGTF-style info |
29 |
files. It will install these for use with OpenSSL, NSS or third-party tools. |
30 |
|
31 |
It works based on a list of trust anchors, for each of which one or more |
32 |
CRLs should be installed in a CRL store. And for each of these CRLs, one or |
33 |
more URLs can be specified from which the specific CRL can be retrieved. |
34 |
There are several supported formats for CRL stores: |
35 |
.IP openssl |
36 |
has a directory in which |
37 |
.I hash |
38 |
\.r |
39 |
.I i |
40 |
files are stored, one CRL per file, and all CRLs for the trust anchors |
41 |
whose subject distinguished name hashes to |
42 |
.I hash |
43 |
are read and evaluated for each certificate issues by the CAs whose |
44 |
subject name hash matches |
45 |
.I hash |
46 |
|
47 |
OpenSSL in version 1 changes its subject name hashing algorithm, though, so |
48 |
that for one trust anchor |
49 |
.B two |
50 |
hashes could be used, depending on the specific OpenSSL version at hand. If |
51 |
OpenSSL version 1 or higher is used by |
52 |
.I fetch-crl |
53 |
and the default mode is used, each CRL is written out twice, once for each |
54 |
possible hash value. This mode in controlled by the |
55 |
.I opensslmode |
56 |
= { |
57 |
.I dual |
58 |
| |
59 |
.I single |
60 |
} configuration option in the configuration file. |
61 |
.IP pem |
62 |
writes out the CRL in PEM (RFC 1421) format. |
63 |
.IP der |
64 |
writes out the CRL in binary under distinguished encoding rules |
65 |
.IP nss |
66 |
will use the crlutil from the Mozilla NSS tools to add or replace a CRL in |
67 |
the NSS cert8.db database. |
68 |
|
69 |
.P |
70 |
Each CRLs can be retrieved from one of several URLs. These URLs are listed |
71 |
by default in the trust anchor meta-data: the |
72 |
.I .info |
73 |
file or the |
74 |
.I .crl_url |
75 |
file, as shipped with the trust anchor. In the crl_url file, there is one |
76 |
URL per line; in the .info file, the |
77 |
.I crl_url |
78 |
attribute is a semi-colon separated list of URLs. These URLs are then |
79 |
tried in order to retrieve a fresh CRL. Once data has been successfully |
80 |
retrieved, this data is used as the CRL if it passes verification, |
81 |
signature checking and expiration checks. Http, https, ftp and file URLs are |
82 |
supported. If data for a CRL has been downloaded but this data fails |
83 |
any of the subsequent checks (signature validation, freshness), the CRL |
84 |
data is discarded and NO further URLs are tried for this CRL! |
85 |
|
86 |
URLs can be pre-pended or post-pended to the default list via the |
87 |
configuration file. This can be used to prefer a local mirror repository |
88 |
over any URLs shipped by the trust anchor provider, without the need to |
89 |
modify the trust anchor metadata. By post-pending a URL, a 'last-resort' |
90 |
download location can be added in case the CA provided URLs cannot be |
91 |
used. The pre- and post-pended URLS are subject to token expansion of the |
92 |
tokens |
93 |
.IR @ALIAS@ ", " @ANCHORNAME@ ", and " @R@ , |
94 |
where |
95 |
.I R |
96 |
is the sequence number of the CRL on a per-trust anchor basis. |
97 |
|
98 |
Retrieved CRLs may be PEM (RFC1421) or DER encoded. They are automatically |
99 |
converted as needed by fetch-crl, using the OpenSSL command-line tool. |
100 |
|
101 |
Retrieving a CRL without having an accompanying CA root certificate |
102 |
in an OpenSSL-accessible form (like |
103 |
.I @ALIAS@.0 |
104 |
or |
105 |
.I @ANCHORNAME@.@R@ |
106 |
will result in a verification failures. The CA lookup directory |
107 |
and patterns can be configured via the configuration file |
108 |
|
109 |
.SH TOKEN EXPANSION |
110 |
In paths and name templates, tokens are expanded to allow a |
111 |
single pattern to be used for all trust anchors. The |
112 |
.IR nametemplate_* , |
113 |
.IR catemplate , |
114 |
.IR prepend_url , |
115 |
and |
116 |
.I postpend_url |
117 |
configuration settings are subject to token expansion. |
118 |
|
119 |
The following tokens are recognised |
120 |
.IP @ALIAS@ |
121 |
The alias name of the trust anchor as defined in the |
122 |
.I info |
123 |
file. If there is no info file and the meta-data is retrieved from |
124 |
.I crl_url |
125 |
files, then the alias is set to the basename (excluding the .crl_url |
126 |
suffix) of the filename of the trust anchor. |
127 |
.IP @ANCHORNAME@ |
128 |
The file name of the trust anchor, without any .info or .url_crl |
129 |
suffix. |
130 |
.IP @R@ |
131 |
The CRL sequence number, counting from 0. Note that most trust anchors |
132 |
only have a single CRL, with sequence number "0". |
133 |
|
134 |
.SH OPTIONS |
135 |
.TP |
136 |
.B \-h --help |
137 |
Show help text. |
138 |
.TP |
139 |
.B \-l --infodir metadata-directory |
140 |
The script will search this directory for files with the |
141 |
suffix '.info' or '.crl_url'. |
142 |
Note: the CRL files to download must be in either PEM or DER format. |
143 |
|
144 |
.TP |
145 |
.B \-o --out outputDirectory |
146 |
Directory where to put the downloaded and processed CRLs. |
147 |
The directory to be used as argument for this option |
148 |
is typically /etc/grid-security/certificates |
149 |
Default: infodir (meta-data directory) |
150 |
|
151 |
.TP |
152 |
.B \-a --agingtolerance hours |
153 |
The maximum age of the locally downloaded CRL before download |
154 |
failures trigger actual error messages. This error message |
155 |
suppression mechanism only works if the CRL has been |
156 |
downloaded at least once and either the crl_url files are |
157 |
named after the hash of the CRL issuer name, or a state directory |
158 |
is used to preserve state across invocations. |
159 |
|
160 |
Default: 24 hour aging tolerance |
161 |
.TP |
162 |
.B \-q --quiet |
163 |
Quiet mode (do not print information messages) |
164 |
|
165 |
.TP |
166 |
.B \-r --randomwait s |
167 |
Wait up to |
168 |
.I s |
169 |
seconds before starting the retrieval process(es). |
170 |
|
171 |
.TP |
172 |
.B \-p --parallelism n |
173 |
Do the retrieval for several trust anchors in parallel, with up to |
174 |
.I n |
175 |
processes doing retrievals. At most |
176 |
.I n |
177 |
downloads will be active at any one time. Multiple CRLs for the |
178 |
same trust anchor are still downloaded sequentially. |
179 |
|
180 |
.SH CONFIGURATION |
181 |
Please see |
182 |
.B http://www.nikhef.nl/grid/gridwiki/index.php/FetchCRL3 |
183 |
for a description of the configuation options. The default location |
184 |
of the configuration file is |
185 |
.IR /etc/fetch-crl.cnf . |
186 |
|
187 |
.SH NOTES |
188 |
Defaults can be set in the fetch-crl system configuration file |
189 |
/etc/fetch-crl.cnf. |
190 |
|
191 |
.SH "SEE ALSO" |
192 |
openssl(1), |
193 |
http://www.nikhef.nl/grid/gridwiki/index.php/FetchCRL3 |
194 |
|
195 |
.SH "DIAGNOSTICS" |
196 |
Exit status is normally 0; |
197 |
if an error occurs, exit status is 1 and diagnostics will be written |
198 |
to standard error. |
199 |
|
200 |
.SH LICENSE |
201 |
Licensed under the Apache License, Version 2.0 (the "License"); |
202 |
|
203 |
.B http://www.apache.org/licenses/LICENSE-2.0 |
204 |
|
205 |
.SH BUGS |
206 |
Although fetch-crl3 will install multiple CRLs in the CRL stores |
207 |
(called '.r0', '.r1', or labelled appropriately in an NSS store), if the |
208 |
number of CRLs decreases the left-overs are not automatically removed. So |
209 |
if the number of CRLs for a particular CA does down from |
210 |
.IR n " to " n-1 , |
211 |
the file |
212 |
.RI '.r n ' |
213 |
must be removed manually. |
214 |
|