/[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 1759 - (hide annotations) (download)
Fri Jun 11 15:41:40 2010 UTC (11 years, 5 months ago) by davidg
Original Path: trunk/fetchcrl/fetch-crl.8
File size: 6852 byte(s)
Moved fetch-crl to a tagger part of the repo

1 davidg 1758 .\" "@(#)$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