]>
Commit | Line | Data |
---|---|---|
d1142857 BK |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
4e46a7af | 5 | X509_STORE, |
d1142857 BK |
6 | X509_STORE_add_cert, X509_STORE_add_crl, X509_STORE_set_depth, |
7 | X509_STORE_set_flags, X509_STORE_set_purpose, X509_STORE_set_trust, | |
4e46a7af | 8 | X509_STORE_add_lookup, |
6725682d SL |
9 | X509_STORE_load_file_with_libctx, X509_STORE_load_file, X509_STORE_load_path, |
10 | X509_STORE_load_store_with_libctx, X509_STORE_load_store, | |
11 | X509_STORE_set_default_paths_with_libctx, X509_STORE_set_default_paths, | |
12 | X509_STORE_load_locations_with_libctx, X509_STORE_load_locations | |
d1142857 BK |
13 | - X509_STORE manipulation |
14 | ||
15 | =head1 SYNOPSIS | |
16 | ||
17 | #include <openssl/x509_vfy.h> | |
18 | ||
4e46a7af RL |
19 | typedef x509_store_st X509_STORE; |
20 | ||
d1142857 BK |
21 | int X509_STORE_add_cert(X509_STORE *ctx, X509 *x); |
22 | int X509_STORE_add_crl(X509_STORE *ctx, X509_CRL *x); | |
23 | int X509_STORE_set_depth(X509_STORE *store, int depth); | |
24 | int X509_STORE_set_flags(X509_STORE *ctx, unsigned long flags); | |
25 | int X509_STORE_set_purpose(X509_STORE *ctx, int purpose); | |
26 | int X509_STORE_set_trust(X509_STORE *ctx, int trust); | |
27 | ||
4e46a7af RL |
28 | X509_LOOKUP *X509_STORE_add_lookup(X509_STORE *store, |
29 | X509_LOOKUP_METHOD *meth); | |
30 | ||
6725682d SL |
31 | int X509_STORE_set_default_paths_with_libctx(X509_STORE *ctx, |
32 | OPENSSL_CTX *libctx, | |
33 | const char *propq); | |
849d91a6 | 34 | int X509_STORE_set_default_paths(X509_STORE *ctx); |
6725682d SL |
35 | int X509_STORE_load_file_with_libctx(X509_STORE *ctx, const char *file, |
36 | OPENSSL_CTX *libctx, const char *propq); | |
849d91a6 RL |
37 | int X509_STORE_load_file(X509_STORE *ctx, const char *file); |
38 | int X509_STORE_load_path(X509_STORE *ctx, const char *dir); | |
6725682d SL |
39 | int X509_STORE_load_store_with_libctx(X509_STORE *ctx, const char *uri, |
40 | OPENSSL_CTX *libctx, const char *propq); | |
849d91a6 | 41 | int X509_STORE_load_store(X509_STORE *ctx, const char *uri); |
6725682d SL |
42 | int X509_STORE_load_locations_with_libctx(X509_STORE *ctx, |
43 | const char *file, const char *dir, | |
44 | OPENSSL_CTX *libctx, | |
45 | const char *propq); | |
d1142857 BK |
46 | int X509_STORE_load_locations(X509_STORE *ctx, |
47 | const char *file, const char *dir); | |
d1142857 BK |
48 | |
49 | =head1 DESCRIPTION | |
50 | ||
51 | The B<X509_STORE> structure is intended to be a consolidated mechanism for | |
52 | holding information about X.509 certificates and CRLs, and constructing | |
53 | and validating chains of certificates terminating in trusted roots. | |
54 | It admits multiple lookup mechanisms and efficient scaling performance | |
55 | with large numbers of certificates, and a great deal of flexibility in | |
56 | how validation and policy checks are performed. | |
57 | ||
58 | L<X509_STORE_new(3)> creates an empty B<X509_STORE> structure, which contains | |
59 | no information about trusted certificates or where such certificates | |
60 | are located on disk, and is generally not usable. Normally, trusted | |
61 | certificates will be added to the B<X509_STORE> to prepare it for use, | |
62 | via mechanisms such as X509_STORE_add_lookup() and X509_LOOKUP_file(), or | |
63 | PEM_read_bio_X509_AUX() and X509_STORE_add_cert(). CRLs can also be added, | |
64 | and many behaviors configured as desired. | |
65 | ||
66 | Once the B<X509_STORE> is suitably configured, X509_STORE_CTX_new() is | |
67 | used to instantiate a single-use B<X509_STORE_CTX> for each chain-building | |
68 | and verification operation. That process includes providing the end-entity | |
69 | certificate to be verified and an additional set of untrusted certificates | |
70 | that may be used in chain-building. As such, it is expected that the | |
71 | certificates included in the B<X509_STORE> are certificates that represent | |
72 | trusted entities such as root certificate authorities (CAs). | |
73 | OpenSSL represents these trusted certificates internally as B<X509> objects | |
74 | with an associated B<X509_CERT_AUX>, as are produced by | |
75 | PEM_read_bio_X509_AUX() and similar routines that refer to X509_AUX. | |
76 | The public interfaces that operate on such trusted certificates still | |
77 | operate on pointers to B<X509> objects, though. | |
78 | ||
79 | X509_STORE_add_cert() and X509_STORE_add_crl() add the respective object | |
80 | to the B<X509_STORE>'s local storage. Untrusted objects should not be | |
86333b6e PY |
81 | added in this way. The added object's reference count is incremented by one, |
82 | hence the caller retains ownership of the object and needs to free it when it | |
83 | is no longer needed. | |
d1142857 BK |
84 | |
85 | X509_STORE_set_depth(), X509_STORE_set_flags(), X509_STORE_set_purpose(), | |
86 | X509_STORE_set_trust(), and X509_STORE_set1_param() set the default values | |
87 | for the corresponding values used in certificate chain validation. Their | |
88 | behavior is documented in the corresponding B<X509_VERIFY_PARAM> manual | |
89 | pages, e.g., L<X509_VERIFY_PARAM_set_depth(3)>. | |
90 | ||
4e46a7af RL |
91 | X509_STORE_add_lookup() finds or creates a L<X509_LOOKUP(3)> with the |
92 | L<X509_LOOKUP_METHOD(3)> I<meth> and adds it to the B<X509_STORE> | |
93 | I<store>. This also associates the B<X509_STORE> with the lookup, so | |
94 | B<X509_LOOKUP> functions can look up objects in that store. | |
95 | ||
6725682d SL |
96 | X509_STORE_load_file_with_libctx() loads trusted certificate(s) into an |
97 | B<X509_STORE> from a given file. The library context I<libctx> and property | |
98 | query <propq> are used when fetching algorithms from providers. | |
99 | ||
100 | X509_STORE_load_file() is similar to X509_STORE_load_file_with_libctx() but | |
101 | uses NULL for the library context I<libctx> and property query <propq>. | |
849d91a6 RL |
102 | |
103 | X509_STORE_load_path() loads trusted certificate(s) into an | |
104 | B<X509_STORE> from a given directory path. | |
105 | The certificates in the directory must be in hashed form, as | |
106 | documented in L<X509_LOOKUP_hash_dir(3)>. | |
107 | ||
6725682d SL |
108 | X509_STORE_load_store_with_libctx() loads trusted certificate(s) into an |
109 | B<X509_STORE> from a store at a given URI. The library context I<libctx> and | |
110 | property query <propq> are used when fetching algorithms from providers. | |
849d91a6 | 111 | |
6725682d SL |
112 | X509_STORE_load_store() is similar to X509_STORE_load_store_with_libctx() but |
113 | uses NULL for the library context I<libctx> and property query <propq>. | |
114 | ||
115 | X509_STORE_load_locations_with_libctx() combines | |
116 | X509_STORE_load_file_with_libctx() and X509_STORE_load_dir() for a given file | |
117 | and/or directory path. | |
849d91a6 RL |
118 | It is permitted to specify just a file, just a directory, or both |
119 | paths. | |
d1142857 | 120 | |
6725682d SL |
121 | X509_STORE_load_locations() is similar to X509_STORE_load_locations_with_libctx() |
122 | but uses NULL for the library context I<libctx> and property query <propq>. | |
123 | ||
124 | X509_STORE_set_default_paths_with_libctx() is somewhat misnamed, in that it does | |
125 | not set what default paths should be used for loading certificates. Instead, | |
d1142857 | 126 | it loads certificates into the B<X509_STORE> from the hardcoded default |
6725682d SL |
127 | paths. The library context I<libctx> and property query <propq> are used when |
128 | fetching algorithms from providers. | |
129 | ||
130 | X509_STORE_set_default_paths() is similar to | |
131 | X509_STORE_set_default_paths_with_libctx() but uses NULL for the library | |
132 | context I<libctx> and property query <propq>. | |
d1142857 BK |
133 | |
134 | =head1 RETURN VALUES | |
135 | ||
136 | X509_STORE_add_cert(), X509_STORE_add_crl(), X509_STORE_set_depth(), | |
6725682d SL |
137 | X509_STORE_set_flags(), X509_STORE_set_purpose(), X509_STORE_set_trust(), |
138 | X509_STORE_load_file_with_libctx(), X509_STORE_load_file(), | |
139 | X509_STORE_load_path(), | |
140 | X509_STORE_load_store_with_libctx(), X509_STORE_load_store(), | |
141 | X509_STORE_load_locations_with_libctx(), X509_STORE_load_locations(), | |
142 | X509_STORE_set_default_paths_with_libctx() and X509_STORE_set_default_paths() | |
143 | return 1 on success or 0 on failure. | |
d1142857 | 144 | |
4e46a7af RL |
145 | X509_STORE_add_lookup() returns the found or created |
146 | L<X509_LOOKUP(3)>, or NULL on error. | |
147 | ||
d1142857 BK |
148 | =head1 SEE ALSO |
149 | ||
150 | L<X509_LOOKUP_hash_dir(3)>. | |
151 | L<X509_VERIFY_PARAM_set_depth(3)>. | |
152 | L<X509_STORE_new(3)>, | |
153 | L<X509_STORE_get0_param(3)> | |
154 | ||
6725682d SL |
155 | =head1 HISTORY |
156 | ||
157 | The functions X509_STORE_set_default_paths_with_libctx(), | |
158 | X509_STORE_load_file_with_libctx(), X509_STORE_load_store_with_libctx() and | |
159 | X509_STORE_load_locations_with_libctx() were added in OpenSSL 3.0. | |
160 | ||
d1142857 BK |
161 | =head1 COPYRIGHT |
162 | ||
33388b44 | 163 | Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved. |
d1142857 | 164 | |
4746f25a | 165 | Licensed under the Apache License 2.0 (the "License"). You may not use |
d1142857 BK |
166 | this file except in compliance with the License. You can obtain a copy |
167 | in the file LICENSE in the source distribution or at | |
168 | L<https://www.openssl.org/source/license.html>. | |
169 | ||
170 | =cut |