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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3135 - (hide annotations) (download)
Mon Nov 14 12:33:38 2016 UTC (5 years ago) by davidg
File size: 7588 byte(s)
Tagged version 3.0.18 with postprocessing hooks

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

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