]>
Commit | Line | Data |
---|---|---|
c03726ca RS |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
849d91a6 | 5 | X509_LOOKUP_hash_dir, X509_LOOKUP_file, X509_LOOKUP_store, |
c03726ca RS |
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 | ||
e9b77246 | 13 | #include <openssl/x509_vfy.h> |
c03726ca | 14 | |
e9b77246 BB |
15 | X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void); |
16 | X509_LOOKUP_METHOD *X509_LOOKUP_file(void); | |
849d91a6 | 17 | X509_LOOKUP_METHOD *X509_LOOKUP_store(void); |
c03726ca | 18 | |
e9b77246 BB |
19 | int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type); |
20 | int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type); | |
21 | int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type); | |
c03726ca RS |
22 | |
23 | =head1 DESCRIPTION | |
24 | ||
25 | B<X509_LOOKUP_hash_dir> and B<X509_LOOKUP_file> are two certificate | |
26 | lookup methods to use with B<X509_STORE>, provided by OpenSSL library. | |
27 | ||
8f243018 | 28 | Users of the library typically do not need to create instances of these |
c03726ca RS |
29 | methods manually, they would be created automatically by |
30 | L<X509_STORE_load_locations(3)> or | |
31 | L<SSL_CTX_load_verify_locations(3)> | |
32 | functions. | |
33 | ||
34 | Internally loading of certificates and CRLs is implemented via functions | |
35 | B<X509_load_cert_crl_file>, B<X509_load_cert_file> and | |
36 | B<X509_load_crl_file>. These functions support parameter I<type>, which | |
37 | can be one of constants B<FILETYPE_PEM>, B<FILETYPE_ASN1> and | |
38 | B<FILETYPE_DEFAULT>. They load certificates and/or CRLs from specified | |
39 | file into memory cache of B<X509_STORE> objects which given B<ctx> | |
40 | parameter is associated with. | |
41 | ||
42 | Functions B<X509_load_cert_file> and | |
43 | B<X509_load_crl_file> can load both PEM and DER formats depending of | |
44 | type value. Because DER format cannot contain more than one certificate | |
45 | or CRL object (while PEM can contain several concatenated PEM objects) | |
46 | B<X509_load_cert_crl_file> with B<FILETYPE_ASN1> is equivalent to | |
47 | B<X509_load_cert_file>. | |
48 | ||
49 | Constant B<FILETYPE_DEFAULT> with NULL filename causes these functions | |
50 | to load default certificate store file (see | |
c1e35057 | 51 | L<X509_STORE_set_default_paths(3)>. |
c03726ca RS |
52 | |
53 | ||
54 | Functions return number of objects loaded from file or 0 in case of | |
1bc74519 | 55 | error. |
c03726ca RS |
56 | |
57 | Both methods support adding several certificate locations into one | |
58 | B<X509_STORE>. | |
59 | ||
60 | This page documents certificate store formats used by these methods and | |
61 | caching policy. | |
62 | ||
05ea606a | 63 | =head2 File Method |
c03726ca | 64 | |
8f243018 VD |
65 | The B<X509_LOOKUP_file> method loads all the certificates or CRLs |
66 | present in a file into memory at the time the file is added as a | |
67 | lookup source. | |
c03726ca RS |
68 | |
69 | File format is ASCII text which contains concatenated PEM certificates | |
70 | and CRLs. | |
71 | ||
8f243018 VD |
72 | This method should be used by applications which work with a small |
73 | set of CAs. | |
c03726ca | 74 | |
05ea606a | 75 | =head2 Hashed Directory Method |
c03726ca | 76 | |
8f243018 VD |
77 | B<X509_LOOKUP_hash_dir> is a more advanced method, which loads |
78 | certificates and CRLs on demand, and caches them in memory once | |
79 | they are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs | |
80 | upon each lookup, so that newer CRLs are as soon as they appear in | |
81 | the directory. | |
82 | ||
83 | The directory should contain one certificate or CRL per file in PEM format, | |
9c0586d5 | 84 | with a filename of the form I<hash>.I<N> for a certificate, or |
8f243018 VD |
85 | I<hash>.B<r>I<N> for a CRL. |
86 | The I<hash> is the value returned by the L<X509_NAME_hash(3)> function applied | |
87 | to the subject name for certificates or issuer name for CRLs. | |
1903a9b7 RS |
88 | The hash can also be obtained via the B<-hash> option of the |
89 | L<openssl-x509(1)> or L<openssl-crl(1)> commands. | |
8f243018 VD |
90 | |
91 | The .I<N> or .B<r>I<N> suffix is a sequence number that starts at zero, and is | |
92 | incremented consecutively for each certificate or CRL with the same I<hash> | |
93 | value. | |
94 | Gaps in the sequence numbers are not supported, it is assumed that there are no | |
95 | more objects with the same hash beyond the first missing number in the | |
96 | sequence. | |
97 | ||
98 | Sequence numbers make it possible for the directory to contain multiple | |
99 | certificates with same subject name hash value. | |
100 | For example, it is possible to have in the store several certificates with same | |
101 | subject or several CRLs with same issuer (and, for example, different validity | |
102 | period). | |
103 | ||
104 | When checking for new CRLs once one CRL for given hash value is | |
105 | loaded, hash_dir lookup method checks only for certificates with | |
106 | sequence number greater than that of the already cached CRL. | |
107 | ||
108 | Note that the hash algorithm used for subject name hashing changed in OpenSSL | |
109 | 1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL | |
c03726ca RS |
110 | 0.9.8 to 1.0.0. |
111 | ||
1903a9b7 RS |
112 | OpenSSL includes a L<openssl-rehash(1)> utility which creates symlinks with |
113 | hashed names for all files with F<.pem> suffix in a given directory. | |
c03726ca | 114 | |
849d91a6 RL |
115 | =head2 OSSL_STORE Method |
116 | ||
117 | B<X509_LOOKUP_store> is a method that allows access to any store of | |
118 | certificates and CRLs through any loader supported by | |
fadb57e5 | 119 | L<ossl_store(7)>. |
849d91a6 RL |
120 | It works with the help of URIs, which can be direct references to |
121 | certificates or CRLs, but can also be references to catalogues of such | |
122 | objects (that behave like directories). | |
123 | ||
124 | This method overlaps the L</File Method> and L</Hashed Directory Method> | |
125 | because of the 'file:' scheme loader. | |
fadb57e5 | 126 | It does no caching of its own, but can use a caching L<ossl_store(7)> |
849d91a6 RL |
127 | loader, and therefore depends on the loader's capability. |
128 | ||
1f13ad31 PY |
129 | =head1 RETURN VALUES |
130 | ||
849d91a6 RL |
131 | X509_LOOKUP_hash_dir(), X509_LOOKUP_file() and X509_LOOKUP_store() |
132 | always return a valid B<X509_LOOKUP_METHOD> structure. | |
1f13ad31 PY |
133 | |
134 | X509_load_cert_file(), X509_load_crl_file() and X509_load_cert_crl_file() return | |
135 | the number of loaded objects or 0 on error. | |
136 | ||
c03726ca RS |
137 | =head1 SEE ALSO |
138 | ||
8162f6f5 | 139 | L<PEM_read_PrivateKey(3)>, |
c03726ca | 140 | L<X509_STORE_load_locations(3)>, |
9e183d22 | 141 | L<X509_store_add_lookup(3)>, |
c03726ca | 142 | L<SSL_CTX_load_verify_locations(3)>, |
0124f32a | 143 | L<X509_LOOKUP_meth_new(3)>, |
fadb57e5 | 144 | L<ossl_store(7)> |
849d91a6 RL |
145 | |
146 | =head1 HISTORY | |
147 | ||
148 | B<X509_LOOKUP_store> was added in OpenSSL 3.0. | |
c03726ca | 149 | |
e2f92610 RS |
150 | =head1 COPYRIGHT |
151 | ||
849d91a6 | 152 | Copyright 2015-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 153 | |
4746f25a | 154 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
155 | this file except in compliance with the License. You can obtain a copy |
156 | in the file LICENSE in the source distribution or at | |
157 | L<https://www.openssl.org/source/license.html>. | |
158 | ||
159 | =cut |