| blob | 61924eb5d81a5f0c8512ec422bdfd32e8d4cd0e3 |
1 .\" $OpenBSD: X509_LOOKUP_hash_dir.3,v 1.7 2018/03/22 16:06:33 schwarze Exp $
2 .\" full merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
3 .\"
4 .\" This file was written by Victor B. Wagner <vitus@cryptocom.ru>
5 .\" and Claus Assmann.
6 .\" Copyright (c) 2015, 2016, 2017 The OpenSSL Project. All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\"
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in
17 .\" the documentation and/or other materials provided with the
18 .\" distribution.
19 .\"
20 .\" 3. All advertising materials mentioning features or use of this
21 .\" software must display the following acknowledgment:
22 .\" "This product includes software developed by the OpenSSL Project
23 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\" endorse or promote products derived from this software without
27 .\" prior written permission. For written permission, please contact
28 .\" openssl-core@openssl.org.
29 .\"
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\" nor may "OpenSSL" appear in their names without prior written
32 .\" permission of the OpenSSL Project.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" acknowledgment:
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .\"
52 .Dd $Mdocdate: March 22 2018 $
53 .Dt X509_LOOKUP_HASH_DIR 3
54 .Os
55 .Sh NAME
56 .Nm X509_LOOKUP_hash_dir ,
57 .Nm X509_LOOKUP_file ,
58 .Nm X509_load_cert_file ,
59 .Nm X509_load_crl_file ,
60 .Nm X509_load_cert_crl_file
61 .Nd default OpenSSL certificate lookup methods
62 .Sh SYNOPSIS
63 .In openssl/x509_vfy.h
64 .Ft X509_LOOKUP_METHOD *
65 .Fn X509_LOOKUP_hash_dir void
66 .Ft X509_LOOKUP_METHOD *
67 .Fn X509_LOOKUP_file void
68 .Ft int
69 .Fo X509_load_cert_file
70 .Fa "X509_LOOKUP *ctx"
71 .Fa "const char *file"
72 .Fa "int type"
73 .Fc
74 .Ft int
75 .Fo X509_load_crl_file
76 .Fa "X509_LOOKUP *ctx"
77 .Fa "const char *file"
78 .Fa "int type"
79 .Fc
80 .Ft int
81 .Fo X509_load_cert_crl_file
82 .Fa "X509_LOOKUP *ctx"
83 .Fa "const char *file"
84 .Fa "int type"
85 .Fc
86 .Sh DESCRIPTION
87 .Fn X509_LOOKUP_hash_dir
88 and
89 .Fn X509_LOOKUP_file
90 are two certificate lookup methods to use with
91 .Vt X509_STORE ,
92 provided by the OpenSSL library.
93 .Pp
94 Users of the library typically do not need to create instances of these
95 methods manually.
96 They are created automatically by the
97 .Xr X509_STORE_load_locations 3
98 or
99 .Xr SSL_CTX_load_verify_locations 3
100 functions.
101 .Pp
102 Internally, loading of certificates and CRLs is implemented via the functions
103 .Fn X509_load_cert_crl_file ,
104 .Fn X509_load_cert_file
105 and
106 .Fn X509_load_crl_file .
107 These functions support a parameter
108 .Fa type ,
109 which can be one of the constants
110 .Dv FILETYPE_PEM ,
111 .Dv FILETYPE_ASN1 ,
112 and
113 .Dv FILETYPE_DEFAULT .
114 They load certificates and/or CRLs from the specified file into a
115 memory cache of
116 .Vt X509_STORE
117 objects which the given
118 .Fa ctx
119 parameter is associated with.
120 .Pp
121 The functions
122 .Fn X509_load_cert_file
123 and
124 .Fn X509_load_crl_file
125 can load both PEM and DER formats depending on the
126 .Fa type
127 value.
128 Because DER format cannot contain more than one certificate or CRL
129 object (while PEM can contain several concatenated PEM objects),
130 .Fn X509_load_cert_crl_file
131 with
132 .Dv FILETYPE_ASN1
133 is equivalent to
134 .Fn X509_load_cert_file .
135 .Pp
136 The constant
137 .Dv FILETYPE_DEFAULT
138 with
139 .Dv NULL
140 filename causes these functions to load the default certificate
141 store file (see
142 .Xr X509_STORE_set_default_paths 3 ) .
143 .Pp
144 Both methods support adding several certificate locations into one
145 .Sy X509_STORE .
146 .Pp
147 This page documents certificate store formats used by these methods and
148 caching policy.
149 .Ss File Method
150 The
151 .Fn X509_LOOKUP_file
152 method loads all the certificates or CRLs present in a file into memory
153 at the time the file is added as a lookup source.
154 .Pp
155 The file format is ASCII text which contains concatenated PEM
156 certificates and CRLs.
157 .Pp
158 This method should be used by applications which work with a small set
159 of CAs.
160 .Ss Hashed Directory Method
161 .Fa X509_LOOKUP_hash_dir
162 is a more advanced method which loads certificates and CRLs on demand,
163 and caches them in memory once they are loaded.
164 As of OpenSSL 1.0.0, it also checks for newer CRLs upon each lookup, so
165 that newer CRLs are used as soon as they appear in the directory.
166 .Pp
167 The directory should contain one certificate or CRL per file in PEM
168 format, with a file name of the form
169 .Ar hash . Ns Ar N
170 for a certificate, or
171 .Ar hash . Ns Sy r Ns Ar N
172 for a CRL.
173 The
174 .Ar hash
175 is the value returned by the
176 .Xr X509_NAME_hash 3
177 function applied to the subject name for certificates or issuer
178 name for CRLs.
179 The hash can also be obtained via the
180 .Fl hash
181 option of the
182 .Xr openssl 1
183 .Cm x509
184 or
185 .Cm crl
186 commands.
187 .Pp
188 The
189 .Ar N
190 suffix is a sequence number that starts at zero and is incremented
191 consecutively for each certificate or CRL with the same
192 .Ar hash
193 value.
194 Gaps in the sequence numbers are not supported.
195 It is assumed that there are no more objects with the same hash
196 beyond the first missing number in the sequence.
197 .Pp
198 Sequence numbers make it possible for the directory to contain multiple
199 certificates with the same subject name hash value.
200 For example, it is possible to have in the store several certificates
201 with the same subject or several CRLs with the same issuer (and, for
202 example, a different validity period).
203 .Pp
204 When checking for new CRLs, once one CRL for a given hash value is
205 loaded, hash_dir lookup method checks only for certificates with
206 sequence number greater than that of the already cached CRL.
207 .Pp
208 Note that the hash algorithm used for subject name hashing changed in
209 OpenSSL 1.0.0, and all certificate stores have to be rehashed when
210 moving from OpenSSL 0.9.8 to 1.0.0.
211 .Sh RETURN VALUES
212 .Fn X509_LOOKUP_hash_dir
213 and
214 .Fn X509_LOOKUP_file
215 always return a pointer to a static
216 .Vt X509_LOOKUP_METHOD
217 structure.
218 .Pp
219 .Fn X509_load_cert_file ,
220 .Fn X509_load_crl_file ,
221 and
222 .Fn X509_load_cert_crl_file
223 return the number of objects loaded from the
224 .Fa file
225 or 0 on error.
226 .Sh SEE ALSO
227 .Xr d2i_X509_bio 3 ,
228 .Xr PEM_read_PrivateKey 3 ,
229 .Xr SSL_CTX_load_verify_locations 3 ,
230 .Xr X509_STORE_load_locations 3
231 .Sh HISTORY
232 .Fn X509_LOOKUP_hash_dir ,
233 .Fn X509_LOOKUP_file ,
234 and
235 .Fn X509_load_cert_file
236 appeared before SSLeay 0.8.
237 .Fn X509_load_crl_file
238 first appeared in SSLeay 0.9.0.
239 These functions have been available since
240 .Ox 2.4 .
241 .Pp
242 .Fn X509_load_cert_crl_file
243 first appeared in OpenSSL 0.9.5 and has been available since
244 .Ox 2.7 .