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