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