]>
Commit | Line | Data |
---|---|---|
356c06c7 RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_load_verify_locations - set default locations for trusted CA | |
6 | certificates | |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | #include <openssl/ssl.h> | |
11 | ||
12 | int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, | |
13 | const char *CApath); | |
14 | ||
15 | =head1 DESCRIPTION | |
16 | ||
17 | SSL_CTX_load_verify_locations() specifies the locations for B<ctx>, at | |
18 | which CA certificates for verification purposes are located. The certificates | |
19 | available via B<CAfile> and B<CApath> are trusted. | |
20 | ||
21 | =head1 NOTES | |
22 | ||
23 | If B<CAfile> is not NULL, it points to a file of CA certificates in PEM | |
24 | format. The file can contain several CA certificates identified by | |
25 | ||
26 | -----BEGIN CERTIFICATE----- | |
27 | ... (CA certificate in base64 encoding) ... | |
28 | -----END CERTIFICATE----- | |
29 | ||
30 | sequences. Before, between, and after the certificates text is allowed | |
31 | which can be used e.g. for descriptions of the certificates. | |
32 | ||
33 | The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations() | |
34 | function. | |
35 | ||
356c06c7 RL |
36 | If B<CApath> is not NULL, it points to a directory containing CA certificates |
37 | in PEM format. The files each contain one CA certificate. The files are | |
38 | looked up by the CA subject name hash value, which must hence be available. | |
553615f5 RL |
39 | If more than one CA certificate with the same name hash value exist, the |
40 | extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search | |
41 | is performed in the ordering of the extension number, regardless of other | |
42 | properties of the certificates. | |
356c06c7 RL |
43 | Use the B<c_rehash> utility to create the necessary links. |
44 | ||
d766a23d | 45 | The certificates in B<CApath> are only looked up when required, e.g. when |
356c06c7 RL |
46 | building the certificate chain or when actually performing the verification |
47 | of a peer certificate. | |
48 | ||
553615f5 RL |
49 | When looking up CA certificates, the OpenSSL library will first search the |
50 | certificates in B<CAfile>, then those in B<CApath>. Certificate matching | |
51 | is done based on the subject name, the key identifier (if present), and the | |
52 | serial number as taken from the certificate to be verified. If these data | |
53 | do not match, the next certificate will be tried. If a first certificate | |
54 | matching the parameters is found, the verification process will be performed; | |
55 | no other certificates for the same parameters will be searched in case of | |
56 | failure. | |
57 | ||
638b0d42 LJ |
58 | In server mode, when requesting a client certificate, the server must send |
59 | the list of CAs of which it will accept client certificates. This list | |
60 | is not influenced by the contents of B<CAfile> or B<CApath> and must | |
3b80e3aa | 61 | explicitly be set using the |
9b86974e | 62 | L<SSL_CTX_set_client_CA_list(3)> |
638b0d42 LJ |
63 | family of functions. |
64 | ||
d766a23d | 65 | When building its own certificate chain, an OpenSSL client/server will |
66ebbb6a | 66 | try to fill in missing certificates from B<CAfile>/B<CApath>, if the |
52d160d8 | 67 | certificate chain was not explicitly specified (see |
9b86974e RS |
68 | L<SSL_CTX_add_extra_chain_cert(3)>, |
69 | L<SSL_CTX_use_certificate(3)>. | |
d766a23d | 70 | |
553615f5 RL |
71 | =head1 WARNINGS |
72 | ||
73 | If several CA certificates matching the name, key identifier, and serial | |
74 | number condition are available, only the first one will be examined. This | |
75 | may lead to unexpected results if the same CA certificate is available | |
76 | with different expiration dates. If a "certificate expired" verification | |
77 | error occurs, no other certificate will be searched. Make sure to not | |
78 | have expired certificates mixed with valid ones. | |
79 | ||
356c06c7 RL |
80 | =head1 EXAMPLES |
81 | ||
82 | Generate a CA certificate file with descriptive text from the CA certificates | |
83 | ca1.pem ca2.pem ca3.pem: | |
84 | ||
85 | #!/bin/sh | |
86 | rm CAfile.pem | |
87 | for i in ca1.pem ca2.pem ca3.pem ; do | |
88 | openssl x509 -in $i -text >> CAfile.pem | |
89 | done | |
90 | ||
91 | Prepare the directory /some/where/certs containing several CA certificates | |
92 | for use as B<CApath>: | |
93 | ||
94 | cd /some/where/certs | |
53fe8d5b | 95 | c_rehash . |
356c06c7 RL |
96 | |
97 | =head1 RETURN VALUES | |
98 | ||
99 | The following return values can occur: | |
100 | ||
101 | =over 4 | |
102 | ||
c8919dde | 103 | =item Z<>0 |
356c06c7 RL |
104 | |
105 | The operation failed because B<CAfile> and B<CApath> are NULL or the | |
106 | processing at one of the locations specified failed. Check the error | |
107 | stack to find out the reason. | |
108 | ||
c8919dde | 109 | =item Z<>1 |
356c06c7 RL |
110 | |
111 | The operation succeeded. | |
112 | ||
113 | =back | |
114 | ||
115 | =head1 SEE ALSO | |
116 | ||
9b86974e RS |
117 | L<ssl(3)>, |
118 | L<SSL_CTX_set_client_CA_list(3)>, | |
119 | L<SSL_get_client_CA_list(3)>, | |
120 | L<SSL_CTX_use_certificate(3)>, | |
121 | L<SSL_CTX_add_extra_chain_cert(3)>, | |
122 | L<SSL_CTX_set_cert_store(3)> | |
356c06c7 RL |
123 | |
124 | =cut |