]>
Commit | Line | Data |
---|---|---|
356c06c7 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
bdb0e04f RL |
5 | SSL_CTX_load_verify_dir, SSL_CTX_load_verify_file, |
6 | SSL_CTX_load_verify_store, SSL_CTX_set_default_verify_paths, | |
7 | SSL_CTX_set_default_verify_dir, SSL_CTX_set_default_verify_file, | |
8 | SSL_CTX_set_default_verify_store, SSL_CTX_load_verify_locations | |
9 | - set default locations for trusted CA certificates | |
356c06c7 RL |
10 | |
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/ssl.h> | |
14 | ||
bdb0e04f RL |
15 | int SSL_CTX_load_verify_dir(SSL_CTX *ctx, const char *CApath); |
16 | int SSL_CTX_load_verify_file(SSL_CTX *ctx, const char *CAfile); | |
17 | int SSL_CTX_load_verify_store(SSL_CTX *ctx, const char *CAstore); | |
356c06c7 | 18 | |
631fb6af MC |
19 | int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx); |
20 | ||
21 | int SSL_CTX_set_default_verify_dir(SSL_CTX *ctx); | |
631fb6af | 22 | int SSL_CTX_set_default_verify_file(SSL_CTX *ctx); |
bdb0e04f RL |
23 | int SSL_CTX_set_default_verify_store(SSL_CTX *ctx); |
24 | ||
bdb0e04f RL |
25 | int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, |
26 | const char *CApath); | |
631fb6af | 27 | |
356c06c7 RL |
28 | =head1 DESCRIPTION |
29 | ||
c7f837cf TH |
30 | SSL_CTX_load_verify_locations(), SSL_CTX_load_verify_dir(), |
31 | SSL_CTX_load_verify_file(), SSL_CTX_load_verify_store() specifies the | |
32 | locations for B<ctx>, at which CA certificates for verification purposes | |
33 | are located. The certificates available via B<CAfile>, B<CApath> and | |
34 | B<CAstore> are trusted. | |
356c06c7 | 35 | |
f5de06aa | 36 | SSL_CTX_set_default_verify_paths() specifies that the default locations from |
bdb0e04f RL |
37 | which CA certificates are loaded should be used. There is one default directory, |
38 | one default file and one default store. | |
22bb8c25 | 39 | The default CA certificates directory is called F<certs> in the default OpenSSL |
bdb0e04f | 40 | directory, and this is also the default store. |
22bb8c25 | 41 | Alternatively the B<SSL_CERT_DIR> environment variable can be defined to |
bdb0e04f | 42 | override this location. |
22bb8c25 | 43 | The default CA certificates file is called F<cert.pem> in the default |
bdb0e04f | 44 | OpenSSL directory. |
22bb8c25 | 45 | Alternatively the B<SSL_CERT_FILE> environment variable can be defined to |
bdb0e04f | 46 | override this location. |
631fb6af MC |
47 | |
48 | SSL_CTX_set_default_verify_dir() is similar to | |
49 | SSL_CTX_set_default_verify_paths() except that just the default directory is | |
50 | used. | |
51 | ||
52 | SSL_CTX_set_default_verify_file() is similar to | |
53 | SSL_CTX_set_default_verify_paths() except that just the default file is | |
54 | used. | |
55 | ||
bdb0e04f RL |
56 | SSL_CTX_set_default_verify_store() is similar to |
57 | SSL_CTX_set_default_verify_paths() except that just the default store is | |
58 | used. | |
59 | ||
356c06c7 RL |
60 | =head1 NOTES |
61 | ||
62 | If B<CAfile> is not NULL, it points to a file of CA certificates in PEM | |
63 | format. The file can contain several CA certificates identified by | |
64 | ||
65 | -----BEGIN CERTIFICATE----- | |
66 | ... (CA certificate in base64 encoding) ... | |
67 | -----END CERTIFICATE----- | |
68 | ||
69 | sequences. Before, between, and after the certificates text is allowed | |
70 | which can be used e.g. for descriptions of the certificates. | |
71 | ||
72 | The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations() | |
73 | function. | |
74 | ||
356c06c7 RL |
75 | If B<CApath> is not NULL, it points to a directory containing CA certificates |
76 | in PEM format. The files each contain one CA certificate. The files are | |
77 | looked up by the CA subject name hash value, which must hence be available. | |
553615f5 RL |
78 | If more than one CA certificate with the same name hash value exist, the |
79 | extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search | |
80 | is performed in the ordering of the extension number, regardless of other | |
81 | properties of the certificates. | |
356c06c7 RL |
82 | Use the B<c_rehash> utility to create the necessary links. |
83 | ||
d766a23d | 84 | The certificates in B<CApath> are only looked up when required, e.g. when |
356c06c7 RL |
85 | building the certificate chain or when actually performing the verification |
86 | of a peer certificate. | |
87 | ||
553615f5 RL |
88 | When looking up CA certificates, the OpenSSL library will first search the |
89 | certificates in B<CAfile>, then those in B<CApath>. Certificate matching | |
90 | is done based on the subject name, the key identifier (if present), and the | |
91 | serial number as taken from the certificate to be verified. If these data | |
92 | do not match, the next certificate will be tried. If a first certificate | |
93 | matching the parameters is found, the verification process will be performed; | |
94 | no other certificates for the same parameters will be searched in case of | |
95 | failure. | |
96 | ||
bdb0e04f RL |
97 | If B<CAstore> is not NULL, it's a URI for to a store, which may |
98 | represent a single container or a whole catalogue of containers. | |
99 | Apart from the B<CAstore> not necessarily being a local file or | |
100 | directory, it's generally treated the same way as a B<CApath>. | |
101 | ||
638b0d42 LJ |
102 | In server mode, when requesting a client certificate, the server must send |
103 | the list of CAs of which it will accept client certificates. This list | |
104 | is not influenced by the contents of B<CAfile> or B<CApath> and must | |
3b80e3aa | 105 | explicitly be set using the |
9b86974e | 106 | L<SSL_CTX_set_client_CA_list(3)> |
638b0d42 LJ |
107 | family of functions. |
108 | ||
d766a23d | 109 | When building its own certificate chain, an OpenSSL client/server will |
66ebbb6a | 110 | try to fill in missing certificates from B<CAfile>/B<CApath>, if the |
52d160d8 | 111 | certificate chain was not explicitly specified (see |
9b86974e RS |
112 | L<SSL_CTX_add_extra_chain_cert(3)>, |
113 | L<SSL_CTX_use_certificate(3)>. | |
d766a23d | 114 | |
553615f5 RL |
115 | =head1 WARNINGS |
116 | ||
117 | If several CA certificates matching the name, key identifier, and serial | |
118 | number condition are available, only the first one will be examined. This | |
119 | may lead to unexpected results if the same CA certificate is available | |
120 | with different expiration dates. If a "certificate expired" verification | |
121 | error occurs, no other certificate will be searched. Make sure to not | |
122 | have expired certificates mixed with valid ones. | |
123 | ||
356c06c7 RL |
124 | =head1 RETURN VALUES |
125 | ||
631fb6af | 126 | For SSL_CTX_load_verify_locations the following return values can occur: |
356c06c7 RL |
127 | |
128 | =over 4 | |
129 | ||
c8919dde | 130 | =item Z<>0 |
356c06c7 RL |
131 | |
132 | The operation failed because B<CAfile> and B<CApath> are NULL or the | |
133 | processing at one of the locations specified failed. Check the error | |
134 | stack to find out the reason. | |
135 | ||
c8919dde | 136 | =item Z<>1 |
356c06c7 RL |
137 | |
138 | The operation succeeded. | |
139 | ||
140 | =back | |
141 | ||
631fb6af MC |
142 | SSL_CTX_set_default_verify_paths(), SSL_CTX_set_default_verify_dir() and |
143 | SSL_CTX_set_default_verify_file() all return 1 on success or 0 on failure. A | |
144 | missing default location is still treated as a success. | |
145 | ||
4564e77a PY |
146 | =head1 EXAMPLES |
147 | ||
148 | Generate a CA certificate file with descriptive text from the CA certificates | |
149 | ca1.pem ca2.pem ca3.pem: | |
150 | ||
151 | #!/bin/sh | |
152 | rm CAfile.pem | |
153 | for i in ca1.pem ca2.pem ca3.pem ; do | |
154 | openssl x509 -in $i -text >> CAfile.pem | |
155 | done | |
156 | ||
157 | Prepare the directory /some/where/certs containing several CA certificates | |
158 | for use as B<CApath>: | |
159 | ||
160 | cd /some/where/certs | |
161 | c_rehash . | |
162 | ||
356c06c7 RL |
163 | =head1 SEE ALSO |
164 | ||
b97fdb57 | 165 | L<ssl(7)>, |
9b86974e RS |
166 | L<SSL_CTX_set_client_CA_list(3)>, |
167 | L<SSL_get_client_CA_list(3)>, | |
168 | L<SSL_CTX_use_certificate(3)>, | |
169 | L<SSL_CTX_add_extra_chain_cert(3)>, | |
e0b5108c JW |
170 | L<SSL_CTX_set_cert_store(3)>, |
171 | L<SSL_CTX_set_client_CA_list(3)> | |
356c06c7 | 172 | |
e2f92610 RS |
173 | =head1 COPYRIGHT |
174 | ||
00c405b3 | 175 | Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 176 | |
4746f25a | 177 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
178 | this file except in compliance with the License. You can obtain a copy |
179 | in the file LICENSE in the source distribution or at | |
180 | L<https://www.openssl.org/source/license.html>. | |
181 | ||
182 | =cut |