DragonFly On-Line Manual Pages
X509_LOOKUP_HASH_D... DragonFly Library Functions Manual X509_LOOKUP_HASH_D...
NAME
X509_LOOKUP_hash_dir, X509_LOOKUP_file, X509_load_cert_file,
X509_load_crl_file, X509_load_cert_crl_file -- default OpenSSL certifi-
cate lookup methods
SYNOPSIS
#include <openssl/x509_vfy.h>
X509_LOOKUP_METHOD *
X509_LOOKUP_hash_dir(void);
X509_LOOKUP_METHOD *
X509_LOOKUP_file(void);
int
X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type);
int
X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type);
int
X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type);
DESCRIPTION
X509_LOOKUP_hash_dir() and X509_LOOKUP_file() are two certificate lookup
methods to use with X509_STORE, provided by the OpenSSL library.
Users of the library typically do not need to create instances of these
methods manually. They are created automatically by the
X509_STORE_load_locations(3) or SSL_CTX_load_verify_locations(3) func-
tions.
Internally, loading of certificates and CRLs is implemented via the func-
tions X509_load_cert_crl_file(), X509_load_cert_file() and
X509_load_crl_file(). These functions support a parameter type, which
can be one of the constants FILETYPE_PEM, FILETYPE_ASN1, and
FILETYPE_DEFAULT. They load certificates and/or CRLs from the specified
file into a memory cache of X509_STORE objects which the given ctx param-
eter is associated with.
The functions X509_load_cert_file() and X509_load_crl_file() can load
both PEM and DER formats depending on the type value. Because DER format
cannot contain more than one certificate or CRL object (while PEM can
contain several concatenated PEM objects), X509_load_cert_crl_file() with
FILETYPE_ASN1 is equivalent to X509_load_cert_file().
The constant FILETYPE_DEFAULT with NULL filename causes these functions
to load the default certificate store file (see
X509_STORE_set_default_paths(3)).
Both methods support adding several certificate locations into one
X509_STORE.
This page documents certificate store formats used by these methods and
caching policy.
File Method
The X509_LOOKUP_file() method loads all the certificates or CRLs present
in a file into memory at the time the file is added as a lookup source.
The file format is ASCII text which contains concatenated PEM certifi-
cates and CRLs.
This method should be used by applications which work with a small set of
CAs.
Hashed Directory Method
X509_LOOKUP_hash_dir is a more advanced method which loads certificates
and CRLs on demand, and caches them in memory once they are loaded. As
of OpenSSL 1.0.0, it also checks for newer CRLs upon each lookup, so that
newer CRLs are used as soon as they appear in the directory.
The directory should contain one certificate or CRL per file in PEM for-
mat, with a file name of the form hash.N for a certificate, or hash.rN
for a CRL. The hash is the value returned by the X509_NAME_hash(3) func-
tion applied to the subject name for certificates or issuer name for
CRLs. The hash can also be obtained via the -hash option of the
openssl(1) x509 or crl commands.
The N suffix is a sequence number that starts at zero and is incremented
consecutively for each certificate or CRL with the same hash value. Gaps
in the sequence numbers are not supported. It is assumed that there are
no more objects with the same hash beyond the first missing number in the
sequence.
Sequence numbers make it possible for the directory to contain multiple
certificates with the same subject name hash value. For example, it is
possible to have in the store several certificates with the same subject
or several CRLs with the same issuer (and, for example, a different
validity period).
When checking for new CRLs, once one CRL for a given hash value is
loaded, hash_dir lookup method checks only for certificates with sequence
number greater than that of the already cached CRL.
Note that the hash algorithm used for subject name hashing changed in
OpenSSL 1.0.0, and all certificate stores have to be rehashed when moving
from OpenSSL 0.9.8 to 1.0.0.
RETURN VALUES
X509_LOOKUP_hash_dir() and X509_LOOKUP_file() always return a pointer to
a static X509_LOOKUP_METHOD structure.
X509_load_cert_file(), X509_load_crl_file(), and
X509_load_cert_crl_file() return the number of objects loaded from the
file or 0 on error.
SEE ALSO
d2i_X509_bio(3), PEM_read_PrivateKey(3),
SSL_CTX_load_verify_locations(3), X509_STORE_load_locations(3)
HISTORY
X509_LOOKUP_hash_dir(), X509_LOOKUP_file(), and X509_load_cert_file()
first appeared in SSLeay 0.8.0. X509_load_crl_file() first appeared in
SSLeay 0.9.0. These functions have been available since OpenBSD 2.4.
X509_load_cert_crl_file() first appeared in OpenSSL 0.9.5 and has been
available since OpenBSD 2.7.
DragonFly 5.5 March 27, 2018 DragonFly 5.5