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