Debian Codegraph @

upstream/debian-unstable/man3/X509_LOOKUP_hash_dir.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "X509_LOOKUP_HASH_DIR 3SSL"
58 .TH X509_LOOKUP_HASH_DIR 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 X509_LOOKUP_hash_dir, X509_LOOKUP_file, X509_LOOKUP_store,
65 X509_load_cert_file_ex, X509_load_cert_file,
66 X509_load_crl_file,
67 X509_load_cert_crl_file_ex, X509_load_cert_crl_file
68 \&\- Default OpenSSL certificate lookup methods
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 1
72 \& #include <openssl/x509_vfy.h>
73 \&
74 \& X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void);
75 \& X509_LOOKUP_METHOD *X509_LOOKUP_file(void);
76 \& X509_LOOKUP_METHOD *X509_LOOKUP_store(void);
77 \&
78 \& int X509_load_cert_file_ex(X509_LOOKUP *ctx, const char *file, int type,
79 \& OSSL_LIB_CTX *libctx, const char *propq);
80 \& int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type);
81 \& int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type);
82 \& int X509_load_cert_crl_file_ex(X509_LOOKUP *ctx, const char *file, int type,
83 \& OSSL_LIB_CTX *libctx, const char *propq);
84 \& int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type);
85 .Ve
86 .SH DESCRIPTION
87 .IX Header "DESCRIPTION"
88 \&\fBX509_LOOKUP_hash_dir\fR and \fBX509_LOOKUP_file\fR are two certificate
89 lookup methods to use with \fBX509_STORE\fR, provided by OpenSSL library.
90 .PP
91 Users of the library typically do not need to create instances of these
92 methods manually, they would be created automatically by
93 \&\fBX509_STORE_load_locations\fR\|(3) or
94 \&\fBSSL_CTX_load_verify_locations\fR\|(3)
95 functions.
96 .PP
97 Internally loading of certificates and CRLs is implemented via functions
98 \&\fBX509_load_cert_crl_file\fR, \fBX509_load_cert_file\fR and
99 \&\fBX509_load_crl_file\fR. These functions support parameter \fItype\fR, which
100 can be one of constants \fBFILETYPE_PEM\fR, \fBFILETYPE_ASN1\fR and
101 \&\fBFILETYPE_DEFAULT\fR. They load certificates and/or CRLs from specified
102 file into memory cache of \fBX509_STORE\fR objects which given \fBctx\fR
103 parameter is associated with.
104 .PP
105 Functions \fBX509_load_cert_file\fR and
106 \&\fBX509_load_crl_file\fR can load both PEM and DER formats depending of
107 type value. Because DER format cannot contain more than one certificate
108 or CRL object (while PEM can contain several concatenated PEM objects)
109 \&\fBX509_load_cert_crl_file\fR with \fBFILETYPE_ASN1\fR is equivalent to
110 \&\fBX509_load_cert_file\fR.
111 .PP
112 Constant \fBFILETYPE_DEFAULT\fR with NULL filename causes these functions
113 to load default certificate store file (see
114 \&\fBX509_STORE_set_default_paths\fR\|(3).
115 .PP
116 Functions return number of objects loaded from file or 0 in case of
117 error.
118 .PP
119 Both methods support adding several certificate locations into one
120 \&\fBX509_STORE\fR.
121 .PP
122 This page documents certificate store formats used by these methods and
123 caching policy.
124 .SS "File Method"
125 .IX Subsection "File Method"
126 The \fBX509_LOOKUP_file\fR method loads all the certificates or CRLs
127 present in a file into memory at the time the file is added as a
128 lookup source.
129 .PP
130 File format is ASCII text which contains concatenated PEM certificates
131 and CRLs.
132 .PP
133 This method should be used by applications which work with a small
134 set of CAs.
135 .SS "Hashed Directory Method"
136 .IX Subsection "Hashed Directory Method"
137 \&\fBX509_LOOKUP_hash_dir\fR is a more advanced method, which loads
138 certificates and CRLs on demand, and caches them in memory once
139 they are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs
140 upon each lookup, so that newer CRLs are as soon as they appear in
141 the directory.
142 .PP
143 The directory should contain one certificate or CRL per file in PEM format,
144 with a filename of the form \fIhash\fR.\fIN\fR for a certificate, or
145 \&\fIhash\fR.\fBr\fR\fIN\fR for a CRL.
146 The \fIhash\fR is the value returned by the \fBX509_NAME_hash_ex\fR\|(3) function
147 applied to the subject name for certificates or issuer name for CRLs.
148 The hash can also be obtained via the \fB\-hash\fR option of the
149 \&\fBopenssl\-x509\fR\|(1) or \fBopenssl\-crl\fR\|(1) commands.
150 .PP
151 The .\fIN\fR or .\fBr\fR\fIN\fR suffix is a sequence number that starts at zero, and is
152 incremented consecutively for each certificate or CRL with the same \fIhash\fR
153 value.
154 Gaps in the sequence numbers are not supported, it is assumed that there are no
155 more objects with the same hash beyond the first missing number in the
156 sequence.
157 .PP
158 Sequence numbers make it possible for the directory to contain multiple
159 certificates with same subject name hash value.
160 For example, it is possible to have in the store several certificates with same
161 subject or several CRLs with same issuer (and, for example, different validity
162 period).
163 .PP
164 When checking for new CRLs once one CRL for given hash value is
165 loaded, hash_dir lookup method checks only for certificates with
166 sequence number greater than that of the already cached CRL.
167 .PP
168 Note that the hash algorithm used for subject name hashing changed in OpenSSL
169 1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL
170 0.9.8 to 1.0.0.
171 .PP
172 OpenSSL includes a \fBopenssl\-rehash\fR\|(1) utility which creates symlinks with
173 hashed names for all files with \fI.pem\fR suffix in a given directory.
174 .SS "OSSL_STORE Method"
175 .IX Subsection "OSSL_STORE Method"
176 \&\fBX509_LOOKUP_store\fR is a method that allows access to any store of
177 certificates and CRLs through any loader supported by
178 \&\fBossl_store\fR\|(7).
179 It works with the help of URIs, which can be direct references to
180 certificates or CRLs, but can also be references to catalogues of such
181 objects (that behave like directories).
182 .PP
183 This method overlaps the "File Method" and "Hashed Directory Method"
184 because of the 'file:' scheme loader.
185 It does no caching of its own, but can use a caching \fBossl_store\fR\|(7)
186 loader, and therefore depends on the loader's capability.
187 .SH "RETURN VALUES"
188 .IX Header "RETURN VALUES"
189 \&\fBX509_LOOKUP_hash_dir()\fR, \fBX509_LOOKUP_file()\fR and \fBX509_LOOKUP_store()\fR
190 always return a valid \fBX509_LOOKUP_METHOD\fR structure.
191 .PP
192 \&\fBX509_load_cert_file()\fR, \fBX509_load_crl_file()\fR and \fBX509_load_cert_crl_file()\fR return
193 the number of loaded objects or 0 on error.
194 .SH "SEE ALSO"
195 .IX Header "SEE ALSO"
196 \&\fBPEM_read_PrivateKey\fR\|(3),
197 \&\fBX509_STORE_load_locations\fR\|(3),
198 \&\fBSSL_CTX_load_verify_locations\fR\|(3),
199 \&\fBX509_LOOKUP_meth_new\fR\|(3),
200 \&\fBossl_store\fR\|(7)
201 .SH HISTORY
202 .IX Header "HISTORY"
203 The functions \fBX509_load_cert_file_ex()\fR,
204 \&\fBX509_load_cert_crl_file_ex()\fR and \fBX509_LOOKUP_store()\fR were added in
205 OpenSSL 3.0.
206 .SH COPYRIGHT
207 .IX Header "COPYRIGHT"
208 Copyright 2015\-2021 The OpenSSL Project Authors. All Rights Reserved.
209 .PP
210 Licensed under the Apache License 2.0 (the "License"). You may not use
211 this file except in compliance with the License. You can obtain a copy
212 in the file LICENSE in the source distribution or at
213 <https://www.openssl.org/source/license.html>.