/[pdpsoft]/trunk/fetchcrl/fetch-crl.8
ViewVC logotype

Contents of /trunk/fetchcrl/fetch-crl.8

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1758 - (show annotations) (download)
Fri Jun 11 15:39:04 2010 UTC (11 years, 5 months ago) by davidg
Original Path: fetchcrl/fetch-crl.8
File size: 6852 byte(s)
Initial import of fetch-crl3

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

grid.support@nikhef.nl
ViewVC Help
Powered by ViewVC 1.1.28