/[pdpsoft]/nl.nikhef.pdp.fetchcrl/tags/fetch-crl-3.0.11/fetch-crl.8
ViewVC logotype

Contents of /nl.nikhef.pdp.fetchcrl/tags/fetch-crl-3.0.11/fetch-crl.8

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2660 - (show annotations) (download)
Sat Jul 6 18:51:25 2013 UTC (8 years, 5 months ago) by davidg
File size: 7152 byte(s)
3.0.11 release with clean-crl 

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

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