Debian Codegraph @

upstream/debian-unstable/man3/X509_STORE_add_cert.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_STORE_ADD_CERT 3SSL"
58 .TH X509_STORE_ADD_CERT 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_STORE,
65 X509_STORE_add_cert, X509_STORE_add_crl, X509_STORE_set_depth,
66 X509_STORE_set_flags, X509_STORE_set_purpose, X509_STORE_set_trust,
67 X509_STORE_add_lookup,
68 X509_STORE_load_file_ex, X509_STORE_load_file, X509_STORE_load_path,
69 X509_STORE_load_store_ex, X509_STORE_load_store,
70 X509_STORE_set_default_paths_ex, X509_STORE_set_default_paths,
71 X509_STORE_load_locations_ex, X509_STORE_load_locations
72 \&\- X509_STORE manipulation
73 .SH SYNOPSIS
74 .IX Header "SYNOPSIS"
75 .Vb 1
76 \& #include <openssl/x509_vfy.h>
77 \&
78 \& typedef x509_store_st X509_STORE;
79 \&
80 \& int X509_STORE_add_cert(X509_STORE *xs, X509 *x);
81 \& int X509_STORE_add_crl(X509_STORE *xs, X509_CRL *x);
82 \& int X509_STORE_set_depth(X509_STORE *store, int depth);
83 \& int X509_STORE_set_flags(X509_STORE *xs, unsigned long flags);
84 \& int X509_STORE_set_purpose(X509_STORE *xs, int purpose);
85 \& int X509_STORE_set_trust(X509_STORE *xs, int trust);
86 \&
87 \& X509_LOOKUP *X509_STORE_add_lookup(X509_STORE *store,
88 \& X509_LOOKUP_METHOD *meth);
89 \&
90 \& int X509_STORE_set_default_paths_ex(X509_STORE *xs, OSSL_LIB_CTX *libctx,
91 \& const char *propq);
92 \& int X509_STORE_set_default_paths(X509_STORE *xs);
93 \& int X509_STORE_load_file_ex(X509_STORE *xs, const char *file,
94 \& OSSL_LIB_CTX *libctx, const char *propq);
95 \& int X509_STORE_load_file(X509_STORE *xs, const char *file);
96 \& int X509_STORE_load_path(X509_STORE *xs, const char *dir);
97 \& int X509_STORE_load_store_ex(X509_STORE *xs, const char *uri,
98 \& OSSL_LIB_CTX *libctx, const char *propq);
99 \& int X509_STORE_load_store(X509_STORE *xs, const char *uri);
100 \& int X509_STORE_load_locations_ex(X509_STORE *xs, const char *file,
101 \& const char *dir, OSSL_LIB_CTX *libctx,
102 \& const char *propq);
103 \& int X509_STORE_load_locations(X509_STORE *xs,
104 \& const char *file, const char *dir);
105 .Ve
106 .SH DESCRIPTION
107 .IX Header "DESCRIPTION"
108 The \fBX509_STORE\fR structure is intended to be a consolidated mechanism for
109 holding information about X.509 certificates and CRLs, and constructing
110 and validating chains of certificates terminating in trusted roots.
111 It admits multiple lookup mechanisms and efficient scaling performance
112 with large numbers of certificates, and a great deal of flexibility in
113 how validation and policy checks are performed.
114 .PP
115 Details of the chain building and checking process are described in
116 "Certification Path Building" in \fBopenssl\-verification\-options\fR\|(1) and
117 "Certification Path Validation" in \fBopenssl\-verification\-options\fR\|(1).
118 .PP
119 \&\fBX509_STORE_new\fR\|(3) creates an empty \fBX509_STORE\fR structure, which contains
120 no information about trusted certificates or where such certificates
121 are located on disk, and is generally not usable. Normally, trusted
122 certificates will be added to the \fBX509_STORE\fR to prepare it for use,
123 via mechanisms such as \fBX509_STORE_add_lookup()\fR and \fBX509_LOOKUP_file()\fR, or
124 \&\fBPEM_read_bio_X509_AUX()\fR and \fBX509_STORE_add_cert()\fR. CRLs can also be added,
125 and many behaviors configured as desired.
126 .PP
127 Once the \fBX509_STORE\fR is suitably configured, \fBX509_STORE_CTX_new()\fR is
128 used to instantiate a single-use \fBX509_STORE_CTX\fR for each chain-building
129 and verification operation. That process includes providing the end-entity
130 certificate to be verified and an additional set of untrusted certificates
131 that may be used in chain-building. As such, it is expected that the
132 certificates included in the \fBX509_STORE\fR are certificates that represent
133 trusted entities such as root certificate authorities (CAs).
134 OpenSSL represents these trusted certificates internally as \fBX509\fR objects
135 with an associated \fBX509_CERT_AUX\fR, as are produced by
136 \&\fBPEM_read_bio_X509_AUX()\fR and similar routines that refer to X509_AUX.
137 The public interfaces that operate on such trusted certificates still
138 operate on pointers to \fBX509\fR objects, though.
139 .PP
140 \&\fBX509_STORE_add_cert()\fR and \fBX509_STORE_add_crl()\fR add the respective object
141 to the \fBX509_STORE\fR's local storage. Untrusted objects should not be
142 added in this way. The added object's reference count is incremented by one,
143 hence the caller retains ownership of the object and needs to free it when it
144 is no longer needed.
145 .PP
146 \&\fBX509_STORE_set_depth()\fR, \fBX509_STORE_set_flags()\fR, \fBX509_STORE_set_purpose()\fR,
147 \&\fBX509_STORE_set_trust()\fR, and \fBX509_STORE_set1_param()\fR set the default values
148 for the corresponding values used in certificate chain validation. Their
149 behavior is documented in the corresponding \fBX509_VERIFY_PARAM\fR manual
150 pages, e.g., \fBX509_VERIFY_PARAM_set_depth\fR\|(3). The \fBX509_STORE\fR \fBMUST NOT\fR be NULL.
151 .PP
152 \&\fBX509_STORE_add_lookup()\fR finds or creates a \fBX509_LOOKUP\fR\|(3) with the
153 \&\fBX509_LOOKUP_METHOD\fR\|(3) \fImeth\fR and adds it to the \fBX509_STORE\fR
154 \&\fIstore\fR. This also associates the \fBX509_STORE\fR with the lookup, so
155 \&\fBX509_LOOKUP\fR functions can look up objects in that store.
156 .PP
157 \&\fBX509_STORE_load_file_ex()\fR loads trusted certificate(s) into an
158 \&\fBX509_STORE\fR from a given file. The library context \fIlibctx\fR and property
159 query \fIpropq\fR are used when fetching algorithms from providers.
160 .PP
161 \&\fBX509_STORE_load_file()\fR is similar to \fBX509_STORE_load_file_ex()\fR but
162 uses NULL for the library context \fIlibctx\fR and property query \fIpropq\fR.
163 .PP
164 \&\fBX509_STORE_load_path()\fR loads trusted certificate(s) into an
165 \&\fBX509_STORE\fR from a given directory path.
166 The certificates in the directory must be in hashed form, as
167 documented in \fBX509_LOOKUP_hash_dir\fR\|(3).
168 .PP
169 \&\fBX509_STORE_load_store_ex()\fR loads trusted certificate(s) into an
170 \&\fBX509_STORE\fR from a store at a given URI. The library context \fIlibctx\fR and
171 property query \fIpropq\fR are used when fetching algorithms from providers.
172 .PP
173 \&\fBX509_STORE_load_store()\fR is similar to \fBX509_STORE_load_store_ex()\fR but
174 uses NULL for the library context \fIlibctx\fR and property query \fIpropq\fR.
175 .PP
176 \&\fBX509_STORE_load_locations_ex()\fR combines
177 \&\fBX509_STORE_load_file_ex()\fR and \fBX509_STORE_load_path()\fR for a given file
178 and/or directory path.
179 It is permitted to specify just a file, just a directory, or both
180 paths.
181 .PP
182 \&\fBX509_STORE_load_locations()\fR is similar to \fBX509_STORE_load_locations_ex()\fR
183 but uses NULL for the library context \fIlibctx\fR and property query \fIpropq\fR.
184 .PP
185 \&\fBX509_STORE_set_default_paths_ex()\fR is somewhat misnamed, in that it does
186 not set what default paths should be used for loading certificates. Instead,
187 it loads certificates into the \fBX509_STORE\fR from the hardcoded default
188 paths. The library context \fIlibctx\fR and property query \fIpropq\fR are used when
189 fetching algorithms from providers.
190 .PP
191 \&\fBX509_STORE_set_default_paths()\fR is similar to
192 \&\fBX509_STORE_set_default_paths_ex()\fR but uses NULL for the library
193 context \fIlibctx\fR and property query \fIpropq\fR.
194 .SH "RETURN VALUES"
195 .IX Header "RETURN VALUES"
196 \&\fBX509_STORE_add_cert()\fR, \fBX509_STORE_add_crl()\fR, \fBX509_STORE_set_depth()\fR,
197 \&\fBX509_STORE_set_flags()\fR, \fBX509_STORE_set_purpose()\fR, \fBX509_STORE_set_trust()\fR,
198 \&\fBX509_STORE_load_file_ex()\fR, \fBX509_STORE_load_file()\fR,
199 \&\fBX509_STORE_load_path()\fR,
200 \&\fBX509_STORE_load_store_ex()\fR, \fBX509_STORE_load_store()\fR,
201 \&\fBX509_STORE_load_locations_ex()\fR, \fBX509_STORE_load_locations()\fR,
202 \&\fBX509_STORE_set_default_paths_ex()\fR and \fBX509_STORE_set_default_paths()\fR
203 return 1 on success or 0 on failure.
204 .PP
205 \&\fBX509_STORE_add_lookup()\fR returns the found or created
206 \&\fBX509_LOOKUP\fR\|(3), or NULL on error.
207 .SH "SEE ALSO"
208 .IX Header "SEE ALSO"
209 \&\fBX509_LOOKUP_hash_dir\fR\|(3).
210 \&\fBX509_VERIFY_PARAM_set_depth\fR\|(3).
211 \&\fBX509_STORE_new\fR\|(3),
212 \&\fBX509_STORE_get0_param\fR\|(3)
213 .SH HISTORY
214 .IX Header "HISTORY"
215 The functions \fBX509_STORE_set_default_paths_ex()\fR,
216 \&\fBX509_STORE_load_file_ex()\fR, \fBX509_STORE_load_store_ex()\fR and
217 \&\fBX509_STORE_load_locations_ex()\fR were added in OpenSSL 3.0.
218 .SH COPYRIGHT
219 .IX Header "COPYRIGHT"
220 Copyright 2017\-2021 The OpenSSL Project Authors. All Rights Reserved.
221 .PP
222 Licensed under the Apache License 2.0 (the "License"). You may not use
223 this file except in compliance with the License. You can obtain a copy
224 in the file LICENSE in the source distribution or at
225 <https://www.openssl.org/source/license.html>.