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

Annotation of /nl.nikhef.pdp.fetchcrl/tags/fetch-crl-3.0.6-1/fetch-crl.8

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2280 - (hide annotations) (download)
Mon Apr 11 07:01:54 2011 UTC (10 years, 8 months ago) by davidg
File size: 6847 byte(s)
Tagged release 3.0.6 fixing parsing of UTF8

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

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