Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_load_verify_locations.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 "SSL_CTX_LOAD_VERIFY_LOCATIONS 3SSL"
58 .TH SSL_CTX_LOAD_VERIFY_LOCATIONS 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 SSL_CTX_load_verify_dir, SSL_CTX_load_verify_file,
65 SSL_CTX_load_verify_store, SSL_CTX_set_default_verify_paths,
66 SSL_CTX_set_default_verify_dir, SSL_CTX_set_default_verify_file,
67 SSL_CTX_set_default_verify_store, SSL_CTX_load_verify_locations
68 \&\- set default locations for trusted CA certificates
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 1
72 \& #include <openssl/ssl.h>
73 \&
74 \& int SSL_CTX_load_verify_dir(SSL_CTX *ctx, const char *CApath);
75 \& int SSL_CTX_load_verify_file(SSL_CTX *ctx, const char *CAfile);
76 \& int SSL_CTX_load_verify_store(SSL_CTX *ctx, const char *CAstore);
77 \&
78 \& int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx);
79 \&
80 \& int SSL_CTX_set_default_verify_dir(SSL_CTX *ctx);
81 \& int SSL_CTX_set_default_verify_file(SSL_CTX *ctx);
82 \& int SSL_CTX_set_default_verify_store(SSL_CTX *ctx);
83 \&
84 \& int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
85 \& const char *CApath);
86 .Ve
87 .SH DESCRIPTION
88 .IX Header "DESCRIPTION"
89 \&\fBSSL_CTX_load_verify_locations()\fR, \fBSSL_CTX_load_verify_dir()\fR,
90 \&\fBSSL_CTX_load_verify_file()\fR, \fBSSL_CTX_load_verify_store()\fR specifies the
91 locations for \fBctx\fR, at which CA certificates for verification purposes
92 are located. The certificates available via \fBCAfile\fR, \fBCApath\fR and
93 \&\fBCAstore\fR are trusted. \fBctx\fR \fBMUST NOT\fR be NULL
94 .PP
95 Details of the certificate verification and chain checking process are
96 described in "Certification Path Validation" in \fBopenssl\-verification\-options\fR\|(1).
97 .PP
98 \&\fBSSL_CTX_set_default_verify_paths()\fR specifies that the default locations from
99 which CA certificates are loaded should be used. There is one default directory,
100 one default file and one default store.
101 The default CA certificates directory is called \fIcerts\fR in the default OpenSSL
102 directory, and this is also the default store.
103 Alternatively the \fBSSL_CERT_DIR\fR environment variable can be defined to
104 override this location.
105 The default CA certificates file is called \fIcert.pem\fR in the default
106 OpenSSL directory.
107 Alternatively the \fBSSL_CERT_FILE\fR environment variable can be defined to
108 override this location.
109 \&\fBctx\fR \fBMUST NOT\fR be NULL.
110 .PP
111 \&\fBSSL_CTX_set_default_verify_dir()\fR is similar to
112 \&\fBSSL_CTX_set_default_verify_paths()\fR except that just the default directory is
113 used.
114 .PP
115 \&\fBSSL_CTX_set_default_verify_file()\fR is similar to
116 \&\fBSSL_CTX_set_default_verify_paths()\fR except that just the default file is
117 used.
118 .PP
119 \&\fBSSL_CTX_set_default_verify_store()\fR is similar to
120 \&\fBSSL_CTX_set_default_verify_paths()\fR except that just the default store is
121 used.
122 .SH NOTES
123 .IX Header "NOTES"
124 If \fBCAfile\fR is not NULL, it points to a file of CA certificates in PEM
125 format. The file can contain several CA certificates identified by
126 .PP
127 .Vb 3
128 \& \-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\-
129 \& ... (CA certificate in base64 encoding) ...
130 \& \-\-\-\-\-END CERTIFICATE\-\-\-\-\-
131 .Ve
132 .PP
133 sequences. Before, between, and after the certificates text is allowed
134 which can be used e.g. for descriptions of the certificates.
135 .PP
136 The \fBCAfile\fR is processed on execution of the \fBSSL_CTX_load_verify_locations()\fR
137 function.
138 .PP
139 If \fBCApath\fR is not NULL, it points to a directory containing CA certificates
140 in PEM format. The files each contain one CA certificate. The files are
141 looked up by the CA subject name hash value, which must hence be available.
142 If more than one CA certificate with the same name hash value exist, the
143 extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search
144 is performed in the ordering of the extension number, regardless of other
145 properties of the certificates.
146 Use the \fBc_rehash\fR utility to create the necessary links.
147 .PP
148 The certificates in \fBCApath\fR are only looked up when required, e.g. when
149 building the certificate chain or when actually performing the verification
150 of a peer certificate.
151 .PP
152 When looking up CA certificates for chain building, the OpenSSL library
153 will search for suitable certificates first in \fBCAfile\fR, then in \fBCApath\fR.
154 Details of the chain building process are described in
155 "Certification Path Building" in \fBopenssl\-verification\-options\fR\|(1).
156 .PP
157 If \fBCAstore\fR is not NULL, it's a URI for to a store, which may
158 represent a single container or a whole catalogue of containers.
159 Apart from the \fBCAstore\fR not necessarily being a local file or
160 directory, it's generally treated the same way as a \fBCApath\fR.
161 .PP
162 In server mode, when requesting a client certificate, the server must send
163 the list of CAs of which it will accept client certificates. This list
164 is not influenced by the contents of \fBCAfile\fR or \fBCApath\fR and must
165 explicitly be set using the
166 \&\fBSSL_CTX_set_client_CA_list\fR\|(3)
167 family of functions.
168 .PP
169 When building its own certificate chain, an OpenSSL client/server will
170 try to fill in missing certificates from \fBCAfile\fR/\fBCApath\fR, if the
171 certificate chain was not explicitly specified (see
172 \&\fBSSL_CTX_add_extra_chain_cert\fR\|(3),
173 \&\fBSSL_CTX_use_certificate\fR\|(3).
174 .SH WARNINGS
175 .IX Header "WARNINGS"
176 If several CA certificates matching the name, key identifier, and serial
177 number condition are available, only the first one will be examined. This
178 may lead to unexpected results if the same CA certificate is available
179 with different expiration dates. If a "certificate expired" verification
180 error occurs, no other certificate will be searched. Make sure to not
181 have expired certificates mixed with valid ones.
182 .SH "RETURN VALUES"
183 .IX Header "RETURN VALUES"
184 For SSL_CTX_load_verify_locations the following return values can occur:
185 .IP 0 4
186 The operation failed because \fBCAfile\fR and \fBCApath\fR are NULL or the
187 processing at one of the locations specified failed. Check the error
188 stack to find out the reason.
189 .IP 1 4
190 .IX Item "1"
191 The operation succeeded.
192 .PP
193 \&\fBSSL_CTX_set_default_verify_paths()\fR, \fBSSL_CTX_set_default_verify_dir()\fR and
194 \&\fBSSL_CTX_set_default_verify_file()\fR all return 1 on success or 0 on failure. A
195 missing default location is still treated as a success.
196 .SH EXAMPLES
197 .IX Header "EXAMPLES"
198 Generate a CA certificate file with descriptive text from the CA certificates
199 ca1.pem ca2.pem ca3.pem:
200 .PP
201 .Vb 5
202 \& #!/bin/sh
203 \& rm CAfile.pem
204 \& for i in ca1.pem ca2.pem ca3.pem ; do
205 \& openssl x509 \-in $i \-text >> CAfile.pem
206 \& done
207 .Ve
208 .PP
209 Prepare the directory /some/where/certs containing several CA certificates
210 for use as \fBCApath\fR:
211 .PP
212 .Vb 2
213 \& cd /some/where/certs
214 \& c_rehash .
215 .Ve
216 .SH "SEE ALSO"
217 .IX Header "SEE ALSO"
218 \&\fBssl\fR\|(7),
219 \&\fBSSL_CTX_set_client_CA_list\fR\|(3),
220 \&\fBSSL_get_client_CA_list\fR\|(3),
221 \&\fBSSL_CTX_use_certificate\fR\|(3),
222 \&\fBSSL_CTX_add_extra_chain_cert\fR\|(3),
223 \&\fBSSL_CTX_set_cert_store\fR\|(3),
224 \&\fBSSL_CTX_set_client_CA_list\fR\|(3)
225 .SH COPYRIGHT
226 .IX Header "COPYRIGHT"
227 Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved.
228 .PP
229 Licensed under the Apache License 2.0 (the "License"). You may not use
230 this file except in compliance with the License. You can obtain a copy
231 in the file LICENSE in the source distribution or at
232 <https://www.openssl.org/source/license.html>.