]>
Commit | Line | Data |
---|---|---|
d1142857 BK |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | X509_STORE_add_cert, X509_STORE_add_crl, X509_STORE_set_depth, | |
6 | X509_STORE_set_flags, X509_STORE_set_purpose, X509_STORE_set_trust, | |
7 | X509_STORE_load_locations, | |
8 | X509_STORE_set_default_paths | |
9 | - X509_STORE manipulation | |
10 | ||
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/x509_vfy.h> | |
14 | ||
15 | int X509_STORE_add_cert(X509_STORE *ctx, X509 *x); | |
16 | int X509_STORE_add_crl(X509_STORE *ctx, X509_CRL *x); | |
17 | int X509_STORE_set_depth(X509_STORE *store, int depth); | |
18 | int X509_STORE_set_flags(X509_STORE *ctx, unsigned long flags); | |
19 | int X509_STORE_set_purpose(X509_STORE *ctx, int purpose); | |
20 | int X509_STORE_set_trust(X509_STORE *ctx, int trust); | |
21 | ||
22 | int X509_STORE_load_locations(X509_STORE *ctx, | |
23 | const char *file, const char *dir); | |
24 | int X509_STORE_set_default_paths(X509_STORE *ctx); | |
25 | ||
26 | =head1 DESCRIPTION | |
27 | ||
28 | The B<X509_STORE> structure is intended to be a consolidated mechanism for | |
29 | holding information about X.509 certificates and CRLs, and constructing | |
30 | and validating chains of certificates terminating in trusted roots. | |
31 | It admits multiple lookup mechanisms and efficient scaling performance | |
32 | with large numbers of certificates, and a great deal of flexibility in | |
33 | how validation and policy checks are performed. | |
34 | ||
35 | L<X509_STORE_new(3)> creates an empty B<X509_STORE> structure, which contains | |
36 | no information about trusted certificates or where such certificates | |
37 | are located on disk, and is generally not usable. Normally, trusted | |
38 | certificates will be added to the B<X509_STORE> to prepare it for use, | |
39 | via mechanisms such as X509_STORE_add_lookup() and X509_LOOKUP_file(), or | |
40 | PEM_read_bio_X509_AUX() and X509_STORE_add_cert(). CRLs can also be added, | |
41 | and many behaviors configured as desired. | |
42 | ||
43 | Once the B<X509_STORE> is suitably configured, X509_STORE_CTX_new() is | |
44 | used to instantiate a single-use B<X509_STORE_CTX> for each chain-building | |
45 | and verification operation. That process includes providing the end-entity | |
46 | certificate to be verified and an additional set of untrusted certificates | |
47 | that may be used in chain-building. As such, it is expected that the | |
48 | certificates included in the B<X509_STORE> are certificates that represent | |
49 | trusted entities such as root certificate authorities (CAs). | |
50 | OpenSSL represents these trusted certificates internally as B<X509> objects | |
51 | with an associated B<X509_CERT_AUX>, as are produced by | |
52 | PEM_read_bio_X509_AUX() and similar routines that refer to X509_AUX. | |
53 | The public interfaces that operate on such trusted certificates still | |
54 | operate on pointers to B<X509> objects, though. | |
55 | ||
56 | X509_STORE_add_cert() and X509_STORE_add_crl() add the respective object | |
57 | to the B<X509_STORE>'s local storage. Untrusted objects should not be | |
58 | added in this way. | |
59 | ||
60 | X509_STORE_set_depth(), X509_STORE_set_flags(), X509_STORE_set_purpose(), | |
61 | X509_STORE_set_trust(), and X509_STORE_set1_param() set the default values | |
62 | for the corresponding values used in certificate chain validation. Their | |
63 | behavior is documented in the corresponding B<X509_VERIFY_PARAM> manual | |
64 | pages, e.g., L<X509_VERIFY_PARAM_set_depth(3)>. | |
65 | ||
66 | X509_STORE_load_locations() loads trusted certificate(s) into an | |
67 | B<X509_STORE> from a given file and/or directory path. It is permitted | |
68 | to specify just a file, just a directory, or both paths. The certificates | |
69 | in the directory must be in hashed form, as documented in | |
70 | L<X509_LOOKUP_hash_dir(3)>. | |
71 | ||
72 | X509_STORE_set_default_paths() is somewhat misnamed, in that it does not | |
73 | set what default paths should be used for loading certificates. Instead, | |
74 | it loads certificates into the B<X509_STORE> from the hardcoded default | |
75 | paths. | |
76 | ||
77 | =head1 RETURN VALUES | |
78 | ||
79 | X509_STORE_add_cert(), X509_STORE_add_crl(), X509_STORE_set_depth(), | |
80 | X509_STORE_set_flags(), X509_STORE_set_purpose(), | |
81 | X509_STORE_set_trust(), X509_STORE_load_locations(), and | |
82 | X509_STORE_set_default_paths() return 1 on success or 0 on failure. | |
83 | ||
84 | =head1 SEE ALSO | |
85 | ||
86 | L<X509_LOOKUP_hash_dir(3)>. | |
87 | L<X509_VERIFY_PARAM_set_depth(3)>. | |
88 | L<X509_STORE_new(3)>, | |
89 | L<X509_STORE_get0_param(3)> | |
90 | ||
91 | =head1 COPYRIGHT | |
92 | ||
b0edda11 | 93 | Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved. |
d1142857 | 94 | |
4746f25a | 95 | Licensed under the Apache License 2.0 (the "License"). You may not use |
d1142857 BK |
96 | this file except in compliance with the License. You can obtain a copy |
97 | in the file LICENSE in the source distribution or at | |
98 | L<https://www.openssl.org/source/license.html>. | |
99 | ||
100 | =cut |