Various doc fixes.
[openssl.git] / 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