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

Annotation of /nl.nikhef.pdp.fetchcrl/trunk/fetch-crl.8

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2606 - (hide annotations) (download)
Mon Feb 25 16:00:22 2013 UTC (8 years, 7 months ago) by davidg
File size: 6975 byte(s)
Add documentation on inet6glue option

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 davidg 2606 .RB [ \-\-inet6glue ]
15 davidg 1758 .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 davidg 1924 .I hash.
38 davidg 1758 .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 davidg 2606 .TP
179     .B \-\-inet6glue
180     Load the Net::INET6Glue module to enable IPv6 support in LWP.
181 davidg 1758 .SH CONFIGURATION
182 davidg 2433 See
183 davidg 1758 .B http://www.nikhef.nl/grid/gridwiki/index.php/FetchCRL3
184 davidg 2433 or the included example file for a description of the configuration
185     options. The default location of the configuration file is
186 davidg 1878 .IR /etc/fetch-crl.conf .
187 davidg 1758
188     .SH NOTES
189     Defaults can be set in the fetch-crl system configuration file
190 davidg 1878 /etc/fetch-crl.conf.
191 davidg 1758
192     .SH "SEE ALSO"
193     openssl(1),
194     http://www.nikhef.nl/grid/gridwiki/index.php/FetchCRL3
195    
196     .SH "DIAGNOSTICS"
197     Exit status is normally 0;
198     if an error occurs, exit status is 1 and diagnostics will be written
199     to standard error.
200    
201     .SH LICENSE
202     Licensed under the Apache License, Version 2.0 (the "License");
203    
204     .B http://www.apache.org/licenses/LICENSE-2.0
205    
206     .SH BUGS
207     Although fetch-crl3 will install multiple CRLs in the CRL stores
208     (called '.r0', '.r1', or labelled appropriately in an NSS store), if the
209     number of CRLs decreases the left-overs are not automatically removed. So
210     if the number of CRLs for a particular CA does down from
211     .IR n " to " n-1 ,
212     the file
213     .RI '.r n '
214     must be removed manually.
215    

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