1=pod 2 3=head1 NAME 4 5X509_LOOKUP_hash_dir, X509_LOOKUP_file, X509_LOOKUP_store, 6X509_load_cert_file_ex, X509_load_cert_file, 7X509_load_crl_file, 8X509_load_cert_crl_file_ex, X509_load_cert_crl_file 9- Default OpenSSL certificate lookup methods 10 11=head1 SYNOPSIS 12 13 #include <openssl/x509_vfy.h> 14 15 X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void); 16 X509_LOOKUP_METHOD *X509_LOOKUP_file(void); 17 X509_LOOKUP_METHOD *X509_LOOKUP_store(void); 18 19 int X509_load_cert_file_ex(X509_LOOKUP *ctx, const char *file, int type, 20 OSSL_LIB_CTX *libctx, const char *propq); 21 int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type); 22 int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type); 23 int X509_load_cert_crl_file_ex(X509_LOOKUP *ctx, const char *file, int type, 24 OSSL_LIB_CTX *libctx, const char *propq); 25 int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type); 26 27=head1 DESCRIPTION 28 29B<X509_LOOKUP_hash_dir> and B<X509_LOOKUP_file> are two certificate 30lookup methods to use with B<X509_STORE>, provided by OpenSSL library. 31 32Users of the library typically do not need to create instances of these 33methods manually, they would be created automatically by 34L<X509_STORE_load_locations(3)> or 35L<SSL_CTX_load_verify_locations(3)> 36functions. 37 38Internally loading of certificates and CRLs is implemented via functions 39B<X509_load_cert_crl_file>, B<X509_load_cert_file> and 40B<X509_load_crl_file>. These functions support parameter I<type>, which 41can be one of constants B<FILETYPE_PEM>, B<FILETYPE_ASN1> and 42B<FILETYPE_DEFAULT>. They load certificates and/or CRLs from specified 43file into memory cache of B<X509_STORE> objects which given B<ctx> 44parameter is associated with. 45 46Functions B<X509_load_cert_file> and 47B<X509_load_crl_file> can load both PEM and DER formats depending of 48type value. Because DER format cannot contain more than one certificate 49or CRL object (while PEM can contain several concatenated PEM objects) 50B<X509_load_cert_crl_file> with B<FILETYPE_ASN1> is equivalent to 51B<X509_load_cert_file>. 52 53Constant B<FILETYPE_DEFAULT> with NULL filename causes these functions 54to load default certificate store file (see 55L<X509_STORE_set_default_paths(3)>. 56 57 58Functions return number of objects loaded from file or 0 in case of 59error. 60 61Both methods support adding several certificate locations into one 62B<X509_STORE>. 63 64This page documents certificate store formats used by these methods and 65caching policy. 66 67=head2 File Method 68 69The B<X509_LOOKUP_file> method loads all the certificates or CRLs 70present in a file into memory at the time the file is added as a 71lookup source. 72 73File format is ASCII text which contains concatenated PEM certificates 74and CRLs. 75 76This method should be used by applications which work with a small 77set of CAs. 78 79=head2 Hashed Directory Method 80 81B<X509_LOOKUP_hash_dir> is a more advanced method, which loads 82certificates and CRLs on demand, and caches them in memory once 83they are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs 84upon each lookup, so that newer CRLs are as soon as they appear in 85the directory. 86 87The directory should contain one certificate or CRL per file in PEM format, 88with a filename of the form I<hash>.I<N> for a certificate, or 89I<hash>.B<r>I<N> for a CRL. 90The I<hash> is the value returned by the L<X509_NAME_hash_ex(3)> function 91applied to the subject name for certificates or issuer name for CRLs. 92The hash can also be obtained via the B<-hash> option of the 93L<openssl-x509(1)> or L<openssl-crl(1)> commands. 94 95The .I<N> or .B<r>I<N> suffix is a sequence number that starts at zero, and is 96incremented consecutively for each certificate or CRL with the same I<hash> 97value. 98Gaps in the sequence numbers are not supported, it is assumed that there are no 99more objects with the same hash beyond the first missing number in the 100sequence. 101 102Sequence numbers make it possible for the directory to contain multiple 103certificates with same subject name hash value. 104For example, it is possible to have in the store several certificates with same 105subject or several CRLs with same issuer (and, for example, different validity 106period). 107 108When checking for new CRLs once one CRL for given hash value is 109loaded, hash_dir lookup method checks only for certificates with 110sequence number greater than that of the already cached CRL. 111 112Note that the hash algorithm used for subject name hashing changed in OpenSSL 1131.0.0, and all certificate stores have to be rehashed when moving from OpenSSL 1140.9.8 to 1.0.0. 115 116OpenSSL includes a L<openssl-rehash(1)> utility which creates symlinks with 117hashed names for all files with F<.pem> suffix in a given directory. 118 119=head2 OSSL_STORE Method 120 121B<X509_LOOKUP_store> is a method that allows access to any store of 122certificates and CRLs through any loader supported by 123L<ossl_store(7)>. 124It works with the help of URIs, which can be direct references to 125certificates or CRLs, but can also be references to catalogues of such 126objects (that behave like directories). 127 128This method overlaps the L</File Method> and L</Hashed Directory Method> 129because of the 'file:' scheme loader. 130It does no caching of its own, but can use a caching L<ossl_store(7)> 131loader, and therefore depends on the loader's capability. 132 133=head1 RETURN VALUES 134 135X509_LOOKUP_hash_dir(), X509_LOOKUP_file() and X509_LOOKUP_store() 136always return a valid B<X509_LOOKUP_METHOD> structure. 137 138X509_load_cert_file(), X509_load_crl_file() and X509_load_cert_crl_file() return 139the number of loaded objects or 0 on error. 140 141=head1 SEE ALSO 142 143L<PEM_read_PrivateKey(3)>, 144L<X509_STORE_load_locations(3)>, 145L<SSL_CTX_load_verify_locations(3)>, 146L<X509_LOOKUP_meth_new(3)>, 147L<ossl_store(7)> 148 149=head1 HISTORY 150 151The functions X509_load_cert_file_ex(), 152X509_load_cert_crl_file_ex() and X509_LOOKUP_store() were added in 153OpenSSL 3.0. 154 155=head1 COPYRIGHT 156 157Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved. 158 159Licensed under the Apache License 2.0 (the "License"). You may not use 160this file except in compliance with the License. You can obtain a copy 161in the file LICENSE in the source distribution or at 162L<https://www.openssl.org/source/license.html>. 163 164=cut 165
