doc/crypto/X509_LOOKUP_hash_dir.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 X509_LOOKUP_hash_dir, X509_LOOKUP_file,
   6 X509_load_cert_file,
   7 X509_load_crl_file,
   8 X509_load_cert_crl_file - Default OpenSSL certificate
   9 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
  18   int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type);
  19   int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type);
  20   int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type);
  21
  22 =head1 DESCRIPTION
  23
  24 B<X509_LOOKUP_hash_dir> and B<X509_LOOKUP_file> are two certificate
  25 lookup methods to use with B<X509_STORE>, provided by OpenSSL library.
  26
  27 Users of the library typically do not need to create instanses of these
  28 methods manually, they would be created automatically by
  29 L<X509_STORE_load_locations(3)> or
  30 L<SSL_CTX_load_verify_locations(3)>
  31 functions.
  32
  33 Internally loading of certificates and CRLs is implemented via functions
  34 B<X509_load_cert_crl_file>, B<X509_load_cert_file> and
  35 B<X509_load_crl_file>. These functions support parameter I<type>, which
  36 can be one of constants B<FILETYPE_PEM>, B<FILETYPE_ASN1> and
  37 B<FILETYPE_DEFAULT>. They load certificates and/or CRLs from specified
  38 file into memory cache of B<X509_STORE> objects which given B<ctx>
  39 parameter is associated with.
  40
  41 Functions B<X509_load_cert_file> and
  42 B<X509_load_crl_file> can load both PEM and DER formats depending of
  43 type value. Because DER format cannot contain more than one certificate
  44 or CRL object (while PEM can contain several concatenated PEM objects)
  45 B<X509_load_cert_crl_file> with B<FILETYPE_ASN1> is equivalent to
  46 B<X509_load_cert_file>.
  47
  48 Constant B<FILETYPE_DEFAULT> with NULL filename causes these functions
  49 to load default certificate store file (see
  50 L<X509_STORE_set_default_paths>.
  51
  52
  53 Functions return number of objects loaded from file or 0 in case of
  54 error.
  55
  56 Both methods support adding several certificate locations into one
  57 B<X509_STORE>.
  58
  59 This page documents certificate store formats used by these methods and
  60 caching policy.
  61
  62 =head2  FILE METHOD
  63
  64 B<X509_LOOKUP_file> method loads entire set of certificates and CRLs
  65 into memory immediately when file name is passed to it.
  66
  67 File format is ASCII text which contains concatenated PEM certificates
  68 and CRLs.
  69
  70 This method should be used by applications which work with limited set
  71 of CAs.
  72
  73
  74 =head2 HASHED DIR METHOD
  75
  76 B<X509_LOOKUP_hash_dir> is more sophisticated method, which loads
  77 certificates and CRLs on demand, but caches them in the memory once they
  78 are loaded. However, since OpenSSL 1.0.0beta1 it checks for newer CRLs
  79 upon each lookup, so if newer CRL would appear in the directory, it
  80 would be loaded.
  81
  82 Directory should contain each certificate and CRL in the separate file
  83 in the PEM format, with file name derived from certificate subject (or CRL
  84 issuer) hash, as returned by L<X509_NAME_hash(3)>
  85 function of with option B<-hash> of L<x509(1)> or
  86 L<crl(1)> command.
  87
  88 This hash value is appended by suffix .I<N> for certificates and
  89 B<.r>I<N> for CRLs where I<N> is sequentual
  90 number among certificates with same hash value, so it is possible to
  91 have in the store several certificates with same subject or several CRLs
  92 with same issuer (and, for example, different validity period).
  93
  94 When checking for new CRLs once one CRL for given hash value is loaded,
  95 hash_dir lookup method checks only for certificates with sequentual
  96 number greater than one of already cached CRL.
  97
  98 Note that hash algorithm used for subject hashing is changed in OpenSSL
  99 1.0, so all certificate stores have to be rehashed upon transitopn from
 100 0.9.8 to 1.0.0.
 101
 102 OpenSSL includes utility L<c_rehash(1)> which creates
 103 symlinks with correct hashed names for all files with .pem suffix in the
 104 given directory.
 105
 106 =head1 SEE ALSO
 107
 108 L<pem(3)>, L<d2i_X509_bio(3)>,
 109 L<X509_STORE_load_locations(3)>,
 110 L<X609_store_add_lookup(3)>,
 111 L<SSL_CTX_load_verify_locations(3)>,
 112
 113 =cut
 114