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

.\" "@(#)$Id: fetch-crl.8,v 1.6 2009/09/21 20:22:32 pmacvsdg Exp $"
.\"
.\" 
.TH FETCH-CRL 8 local "Trust Anchor Utilities"
.SH NAME
fetch-crl \- retrieve certificate revocation lists
.SH SYNOPSIS
.ll +8
.B fetch-crl
.RB [ \-c\ config ]
.RB [ \-v [ v .. ] ]
.RB [ \-q ]
.RB [ \-h ]
.RB [ \-\-inet6glue ]
.RB [ \-l\ infopath ]
.RB [ \-o\ outputpath ]
.RB [ \-s\ statepath ]
.RB [ \-a\ agingtolerance ]
.RB [ \-T\ httptimeout ]
.RB [ \-r\ randomwait ]
.RB [ \-p\ parallelism ]
.RB [ \-\-formats\ openssl | pem | der | nss ]\ ..
.ll -8
.SH DESCRIPTION
The 
.I fetch-crl
utility will retrieve certificate revocation lists (CRLs) for a set of 
installed trust anchors, based on crl_url files or IGTF-style info
files. It will install these for use with OpenSSL, NSS or third-party tools.

It works based on a list of trust anchors, for each of which one or more 
CRLs should be installed in a CRL store. And for each of these CRLs, one or
more URLs can be specified from which the specific CRL can be retrieved.
There are several supported formats for CRL stores:
.IP openssl
has a directory in which 
.I hash.
.I i
files are stored, one CRL per file, and all CRLs for the trust anchors 
whose subject distinguished name hashes to
.I hash
are read and evaluated for each certificate issues by the CAs whose
subject name hash matches
.I hash

OpenSSL in version 1 changes its subject name hashing algorithm, though, so
that for one trust anchor 
.B two
hashes could be used, depending on the specific OpenSSL version at hand. If
OpenSSL version 1 or higher is used by 
.I fetch-crl
and the default mode is used, each CRL is written out twice, once for each
possible hash value. This mode in controlled by the
.I opensslmode
= {
.I dual
|
.I single
} configuration option in the configuration file.
.IP pem
writes out the CRL in PEM (RFC 1421) format.
.IP der
writes out the CRL in binary under distinguished encoding rules
.IP nss
will use the crlutil from the Mozilla NSS tools to add or replace a CRL in
the NSS cert8.db database.

.P
Each CRLs can be retrieved from one of several URLs. These URLs are listed
by default in the trust anchor meta-data: the 
.I .info
file or the
.I .crl_url
file, as shipped with the trust anchor. In the crl_url file, there is one
URL per line; in the .info file, the
.I crl_url 
attribute is a semi-colon separated list of URLs. These URLs are then
tried in order to retrieve a fresh CRL. Once data has been successfully
retrieved, this data is used as the CRL if it passes verification,
signature checking and expiration checks. Http, https, ftp and file URLs are
supported. If data for a CRL has been downloaded but this data fails
any of the subsequent checks (signature validation, freshness), the CRL
data is discarded and NO further URLs are tried for this CRL!

URLs can be pre-pended or post-pended to the default list via the
configuration file. This can be used to prefer a local mirror repository
over any URLs shipped by the trust anchor provider, without the need to
modify the trust anchor metadata. By post-pending a URL, a 'last-resort'
download location can be added in case the CA provided URLs cannot be
used. The pre- and post-pended URLS are subject to token expansion of the
tokens
.IR @ALIAS@ ", " @ANCHORNAME@ ", and " @R@ ,
where 
.I R
is the sequence number of the CRL on a per-trust anchor basis.

Retrieved CRLs may be PEM (RFC1421) or DER encoded. They are automatically
converted as needed by fetch-crl, using the OpenSSL command-line tool.

Retrieving a CRL without having an accompanying CA root certificate
in an OpenSSL-accessible form (like
.I @ALIAS@.0
or
.I @ANCHORNAME@.@R@
will result in a verification failures. The CA lookup directory 
and patterns can be configured via the configuration file

.SH TOKEN EXPANSION
In paths and name templates, tokens are expanded to allow a 
single pattern to be used for all trust anchors. The 
.IR nametemplate_* , 
.IR catemplate ,
.IR prepend_url ,
and
.I postpend_url
configuration settings are subject to token expansion.

The following tokens are recognised
.IP @ALIAS@
The alias name of the trust anchor as defined in the 
.I info
file. If there is no info file and the meta-data is retrieved from
.I crl_url
files, then the alias is set to the basename (excluding the .crl_url
suffix) of the filename of the trust anchor.
.IP @ANCHORNAME@
The file name of the trust anchor, without any .info or .url_crl
suffix.
.IP @R@
The CRL sequence number, counting from 0. Note that most trust anchors
only have a single CRL, with sequence number "0".

.SH OPTIONS
.TP
.B \-h --help
Show help text.
.TP
.B \-l --infodir metadata-directory
The script will search this directory for files with the
suffix '.info' or '.crl_url'. 
Note: the CRL files to download must be in either PEM or DER format.

.TP
.B \-o --out  outputDirectory
Directory where to put the downloaded and processed CRLs.
The directory to be used as argument for this option
is typically /etc/grid-security/certificates
Default: infodir (meta-data directory)

.TP
.B \-a --agingtolerance  hours
The maximum age of the locally downloaded CRL before download 
failures trigger actual error messages. This error message
suppression mechanism only works if the CRL has been
downloaded at least once and either the crl_url files are 
named after the hash of the CRL issuer name, or a state directory
is used to preserve state across invocations.

Default: 24 hour aging tolerance
.TP
.B \-q --quiet
Quiet mode (do not print information messages)

.TP
.B \-r --randomwait s
Wait up to 
.I s
seconds before starting the retrieval process(es).

.TP
.B \-p --parallelism n
Do the retrieval for several trust anchors in parallel, with up to
.I n
processes doing retrievals. At most 
.I n
downloads will be active at any one time. Multiple CRLs for the 
same trust anchor are still downloaded sequentially.
.TP
.B \-\-inet6glue
Load the Net::INET6Glue module to enable IPv6 support in LWP.
.SH CONFIGURATION
See 
.B http://www.nikhef.nl/grid/gridwiki/index.php/FetchCRL3
or the included example file for a description of the configuration 
options. The default location of the configuration file is 
.IR /etc/fetch-crl.conf .

.SH NOTES
Defaults can be set in the fetch-crl system configuration file
/etc/fetch-crl.conf.

.SH "SEE ALSO"
openssl(1), 
http://www.nikhef.nl/grid/gridwiki/index.php/FetchCRL3

.SH "DIAGNOSTICS"
Exit status is normally 0;
if an error occurs, exit status is 1 and diagnostics will be written
to standard error.

.SH LICENSE
Licensed under the Apache License, Version 2.0 (the "License"); 

.B http://www.apache.org/licenses/LICENSE-2.0

.SH BUGS
Although fetch-crl3 will install multiple CRLs in the CRL stores 
(called '.r0', '.r1', or labelled appropriately in an NSS store), if the 
number of CRLs decreases the left-overs are not automatically removed. So 
if the number of CRLs for a particular CA does down from 
.IR n " to " n-1 ,
the file 
.RI '.r n '
must be removed manually. 

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://www.nikhef.nl/grid/gridwiki/index.php/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
188	.SH NOTES
189	Defaults can be set in the fetch-crl system configuration file
190	/etc/fetch-crl.conf.
191
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