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