| 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 instances 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(3)>.
|
|---|
| 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 | The B<X509_LOOKUP_file> method loads all the certificates or CRLs
|
|---|
| 65 | present in a file into memory at the time the file is added as a
|
|---|
| 66 | lookup source.
|
|---|
| 67 |
|
|---|
| 68 | File format is ASCII text which contains concatenated PEM certificates
|
|---|
| 69 | and CRLs.
|
|---|
| 70 |
|
|---|
| 71 | This method should be used by applications which work with a small
|
|---|
| 72 | set of CAs.
|
|---|
| 73 |
|
|---|
| 74 | =head2 Hashed Directory Method
|
|---|
| 75 |
|
|---|
| 76 | B<X509_LOOKUP_hash_dir> is a more advanced method, which loads
|
|---|
| 77 | certificates and CRLs on demand, and caches them in memory once
|
|---|
| 78 | they are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs
|
|---|
| 79 | upon each lookup, so that newer CRLs are as soon as they appear in
|
|---|
| 80 | the directory.
|
|---|
| 81 |
|
|---|
| 82 | The directory should contain one certificate or CRL per file in PEM format,
|
|---|
| 83 | with a file name of the form I<hash>.I<N> for a certificate, or
|
|---|
| 84 | I<hash>.B<r>I<N> for a CRL.
|
|---|
| 85 | The I<hash> is the value returned by the L<X509_NAME_hash(3)> function applied
|
|---|
| 86 | to the subject name for certificates or issuer name for CRLs.
|
|---|
| 87 | The hash can also be obtained via the B<-hash> option of the L<x509(1)> or
|
|---|
| 88 | L<crl(1)> commands.
|
|---|
| 89 |
|
|---|
| 90 | The .I<N> or .B<r>I<N> suffix is a sequence number that starts at zero, and is
|
|---|
| 91 | incremented consecutively for each certificate or CRL with the same I<hash>
|
|---|
| 92 | value.
|
|---|
| 93 | Gaps in the sequence numbers are not supported, it is assumed that there are no
|
|---|
| 94 | more objects with the same hash beyond the first missing number in the
|
|---|
| 95 | sequence.
|
|---|
| 96 |
|
|---|
| 97 | Sequence numbers make it possible for the directory to contain multiple
|
|---|
| 98 | certificates with same subject name hash value.
|
|---|
| 99 | For example, it is possible to have in the store several certificates with same
|
|---|
| 100 | subject or several CRLs with same issuer (and, for example, different validity
|
|---|
| 101 | period).
|
|---|
| 102 |
|
|---|
| 103 | When checking for new CRLs once one CRL for given hash value is
|
|---|
| 104 | loaded, hash_dir lookup method checks only for certificates with
|
|---|
| 105 | sequence number greater than that of the already cached CRL.
|
|---|
| 106 |
|
|---|
| 107 | Note that the hash algorithm used for subject name hashing changed in OpenSSL
|
|---|
| 108 | 1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL
|
|---|
| 109 | 0.9.8 to 1.0.0.
|
|---|
| 110 |
|
|---|
| 111 | OpenSSL includes a L<rehash(1)> utility which creates symlinks with correct
|
|---|
| 112 | hashed names for all files with .pem suffix in a given directory.
|
|---|
| 113 |
|
|---|
| 114 | =head1 RETURN VALUES
|
|---|
| 115 |
|
|---|
| 116 | X509_LOOKUP_hash_dir() and X509_LOOKUP_file() always return a valid
|
|---|
| 117 | B<X509_LOOKUP_METHOD> structure.
|
|---|
| 118 |
|
|---|
| 119 | X509_load_cert_file(), X509_load_crl_file() and X509_load_cert_crl_file() return
|
|---|
| 120 | the number of loaded objects or 0 on error.
|
|---|
| 121 |
|
|---|
| 122 | =head1 SEE ALSO
|
|---|
| 123 |
|
|---|
| 124 | L<PEM_read_PrivateKey(3)>,
|
|---|
| 125 | L<X509_STORE_load_locations(3)>,
|
|---|
| 126 | L<X509_store_add_lookup(3)>,
|
|---|
| 127 | L<SSL_CTX_load_verify_locations(3)>,
|
|---|
| 128 | L<X509_LOOKUP_meth_new(3)>,
|
|---|
| 129 |
|
|---|
| 130 | =head1 COPYRIGHT
|
|---|
| 131 |
|
|---|
| 132 | Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 133 |
|
|---|
| 134 | Licensed under the OpenSSL license (the "License"). You may not use
|
|---|
| 135 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 136 | in the file LICENSE in the source distribution or at
|
|---|
| 137 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 138 |
|
|---|
| 139 | =cut
|
|---|
