191511Sobrien=pod 251681Seivind 3139825Simp=head1 NAME 41541Srgrimes 51541SrgrimesX509_LOOKUP_hash_dir, X509_LOOKUP_file, X509_LOOKUP_store, 61541SrgrimesX509_load_cert_file_ex, X509_load_cert_file, 71541SrgrimesX509_load_crl_file, 81541SrgrimesX509_load_cert_crl_file_ex, X509_load_cert_crl_file 91541Srgrimes- Default OpenSSL certificate lookup methods 101541Srgrimes 111541Srgrimes=head1 SYNOPSIS 121541Srgrimes 131541Srgrimes #include <openssl/x509_vfy.h> 141541Srgrimes 151541Srgrimes X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void); 161541Srgrimes X509_LOOKUP_METHOD *X509_LOOKUP_file(void); 171541Srgrimes X509_LOOKUP_METHOD *X509_LOOKUP_store(void); 181541Srgrimes 191541Srgrimes int X509_load_cert_file_ex(X509_LOOKUP *ctx, const char *file, int type, 201541Srgrimes OSSL_LIB_CTX *libctx, const char *propq); 211541Srgrimes int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type); 221541Srgrimes int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type); 231541Srgrimes int X509_load_cert_crl_file_ex(X509_LOOKUP *ctx, const char *file, int type, 241541Srgrimes OSSL_LIB_CTX *libctx, const char *propq); 251541Srgrimes int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type); 261541Srgrimes 271541Srgrimes=head1 DESCRIPTION 281541Srgrimes 291541SrgrimesB<X509_LOOKUP_hash_dir> and B<X509_LOOKUP_file> are two certificate 30139825Simplookup methods to use with B<X509_STORE>, provided by OpenSSL library. 311541Srgrimes 321541SrgrimesUsers of the library typically do not need to create instances of these 3350477Spetermethods manually, they would be created automatically by 341541SrgrimesL<X509_STORE_load_locations(3)> or 351541SrgrimesL<SSL_CTX_load_verify_locations(3)> 361541Srgrimesfunctions. 37158936Sdds 3891511SobrienInternally loading of certificates and CRLs is implemented via functions 39158936SddsB<X509_load_cert_crl_file>, B<X509_load_cert_file> and 401541SrgrimesB<X509_load_crl_file>. These functions support parameter I<type>, which 411541Srgrimescan be one of constants B<FILETYPE_PEM>, B<FILETYPE_ASN1> and 4291511SobrienB<FILETYPE_DEFAULT>. They load certificates and/or CRLs from specified 4391511Sobrienfile into memory cache of B<X509_STORE> objects which given B<ctx> 44138290Sphkparameter is associated with. 4591511Sobrien 4691511SobrienFunctions B<X509_load_cert_file> and 4762168SalfredB<X509_load_crl_file> can load both PEM and DER formats depending of 4891511Sobrientype value. Because DER format cannot contain more than one certificate 4991511Sobrienor CRL object (while PEM can contain several concatenated PEM objects) 50159083SddsB<X509_load_cert_crl_file> with B<FILETYPE_ASN1> is equivalent to 5191511SobrienB<X509_load_cert_file>. 5291511Sobrien 5391511SobrienConstant B<FILETYPE_DEFAULT> with NULL filename causes these functions 541541Srgrimesto load default certificate store file (see 5591511SobrienL<X509_STORE_set_default_paths(3)>. 5691511Sobrien 5791511Sobrien 5891511SobrienFunctions return number of objects loaded from file or 0 in case of 5991511Sobrienerror. 6051681Seivind 6191511SobrienBoth methods support adding several certificate locations into one 6291511SobrienB<X509_STORE>. 6391511Sobrien 64138290SphkThis page documents certificate store formats used by these methods and 65138290Sphkcaching policy. 6691511Sobrien 67140165Sphk=head2 File Method 6891511Sobrien 69116614SseThe B<X509_LOOKUP_file> method loads all the certificates or CRLs 70140165Sphkpresent in a file into memory at the time the file is added as a 71140165Sphklookup source. 72140165Sphk 73116694StruckmanFile format is ASCII text which contains concatenated PEM certificates 74140165Sphkand CRLs. 7591511Sobrien 76100919SjeffThis method should be used by applications which work with a small 77140165Sphkset of CAs. 78100919Sjeff 79140165Sphk=head2 Hashed Directory Method 80144907Sjeff 81144907SjeffB<X509_LOOKUP_hash_dir> is a more advanced method, which loads 8291511Sobriencertificates and CRLs on demand, and caches them in memory once 8391511Sobrienthey are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs 8491511Sobrienupon each lookup, so that newer CRLs are as soon as they appear in 8591511Sobrienthe directory. 8651681Seivind 8751681SeivindThe directory should contain one certificate or CRL per file in PEM format, 88147198Sssouhlalwith a filename of the form I<hash>.I<N> for a certificate, or 8999482SjeffI<hash>.B<r>I<N> for a CRL. 9099516SjeffThe I<hash> is the value returned by the L<X509_NAME_hash_ex(3)> function 91140165Sphkapplied to the subject name for certificates or issuer name for CRLs. 9299482SjeffThe hash can also be obtained via the B<-hash> option of the 9399482SjeffL<openssl-x509(1)> or L<openssl-crl(1)> commands. 9499482Sjeff 95147198SssouhlalThe .I<N> or .B<r>I<N> suffix is a sequence number that starts at zero, and is 9699482Sjeffincremented consecutively for each certificate or CRL with the same I<hash> 9799516Sjeffvalue. 98140165SphkGaps in the sequence numbers are not supported, it is assumed that there are no 9999482Sjeffmore objects with the same hash beyond the first missing number in the 10099482Sjeffsequence. 10199482Sjeff 10291511SobrienSequence numbers make it possible for the directory to contain multiple 10391511Sobriencertificates with same subject name hash value. 10491511SobrienFor example, it is possible to have in the store several certificates with same 10591511Sobriensubject or several CRLs with same issuer (and, for example, different validity 10691511Sobrienperiod). 10791511Sobrien 10891511SobrienWhen checking for new CRLs once one CRL for given hash value is 10991511Sobrienloaded, hash_dir lookup method checks only for certificates with 1101541Srgrimessequence number greater than that of the already cached CRL. 11191511Sobrien 11291511SobrienNote that the hash algorithm used for subject name hashing changed in OpenSSL 1131541Srgrimes1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL 11491511Sobrien0.9.8 to 1.0.0. 1151541Srgrimes 11691511SobrienOpenSSL includes a L<openssl-rehash(1)> utility which creates symlinks with 11791511Sobrienhashed names for all files with F<.pem> suffix in a given directory. 11891511Sobrien 119138290Sphk=head2 OSSL_STORE Method 12091511Sobrien 12191511SobrienB<X509_LOOKUP_store> is a method that allows access to any store of 12291511Sobriencertificates and CRLs through any loader supported by 12391511SobrienL<ossl_store(7)>. 12491511SobrienIt works with the help of URIs, which can be direct references to 125138290Sphkcertificates or CRLs, but can also be references to catalogues of such 126138290Sphkobjects (that behave like directories). 127138290Sphk 128138290SphkThis method overlaps the L</File Method> and L</Hashed Directory Method> 12991511Sobrienbecause of the 'file:' scheme loader. 13091511SobrienIt does no caching of its own, but can use a caching L<ossl_store(7)> 13154499Speterloader, and therefore depends on the loader's capability. 13291511Sobrien 1331541Srgrimes=head1 RETURN VALUES 134138290Sphk 13591511SobrienX509_LOOKUP_hash_dir(), X509_LOOKUP_file() and X509_LOOKUP_store() 1361541Srgrimesalways return a valid B<X509_LOOKUP_METHOD> structure. 13791511Sobrien 13891511SobrienX509_load_cert_file(), X509_load_crl_file() and X509_load_cert_crl_file() return 1391541Srgrimesthe number of loaded objects or 0 on error. 14091511Sobrien 14191511Sobrien=head1 SEE ALSO 14291511Sobrien 14391511SobrienL<PEM_read_PrivateKey(3)>, 14491511SobrienL<X509_STORE_load_locations(3)>, 14591511SobrienL<SSL_CTX_load_verify_locations(3)>, 14691511SobrienL<X509_LOOKUP_meth_new(3)>, 14791511SobrienL<ossl_store(7)> 1481541Srgrimes 149138290Sphk=head1 HISTORY 150138290Sphk 151138290SphkThe functions X509_load_cert_file_ex(), 152138290SphkX509_load_cert_crl_file_ex() and X509_LOOKUP_store() were added in 153138290SphkOpenSSL 3.0. 154138290Sphk 155138290Sphk=head1 COPYRIGHT 156138290Sphk 157138290SphkCopyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved. 158138290Sphk 159138290SphkLicensed under the Apache License 2.0 (the "License"). You may not use 160138290Sphkthis file except in compliance with the License. You can obtain a copy 16191511Sobrienin the file LICENSE in the source distribution or at 162138290SphkL<https://www.openssl.org/source/license.html>. 163138290Sphk 164138290Sphk=cut 16562168Salfred