1112857Sdes=pod 2112857Sdes 3112857Sdes=head1 NAME 4112857Sdes 5112857SdesSSL_CTX_load_verify_locations - set default locations for trusted CA 6112857Sdescertificates 7112857Sdes 8112857Sdes=head1 SYNOPSIS 9112857Sdes 10112857Sdes #include <openssl/ssl.h> 11112857Sdes 12112857Sdes int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, 13112857Sdes const char *CApath); 14112857Sdes 15112857Sdes=head1 DESCRIPTION 16112857Sdes 17112857SdesSSL_CTX_load_verify_locations() specifies the locations for B<ctx>, at 18112857Sdeswhich CA certificates for verification purposes are located. The certificates 19112857Sdesavailable via B<CAfile> and B<CApath> are trusted. 20112857Sdes 21112857Sdes=head1 NOTES 22112857Sdes 23112857SdesIf B<CAfile> is not NULL, it points to a file of CA certificates in PEM 24112857Sdesformat. The file can contain several CA certificates identified by 25112857Sdes 26112857Sdes -----BEGIN CERTIFICATE----- 27112857Sdes ... (CA certificate in base64 encoding) ... 28112857Sdes -----END CERTIFICATE----- 29112857Sdes 30112857Sdessequences. Before, between, and after the certificates text is allowed 31112857Sdeswhich can be used e.g. for descriptions of the certificates. 32112857Sdes 33112857SdesThe B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations() 34112857Sdesfunction. 35112857Sdes 36112857SdesIf B<CApath> is not NULL, it points to a directory containing CA certificates 37112857Sdesin PEM format. The files each contain one CA certificate. The files are 38112857Sdeslooked up by the CA subject name hash value, which must hence be available. 39112857SdesIf more than one CA certificate with the same name hash value exist, the 40112857Sdesextension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search 41112857Sdesis performed in the ordering of the extension number, regardless of other 42112857Sdesproperties of the certificates. 43112857SdesUse the B<c_rehash> utility to create the necessary links. 44112857Sdes 45112857SdesThe certificates in B<CApath> are only looked up when required, e.g. when 46112857Sdesbuilding the certificate chain or when actually performing the verification 47112857Sdesof a peer certificate. 48112857Sdes 49112857SdesWhen looking up CA certificates, the OpenSSL library will first search the 50112857Sdescertificates in B<CAfile>, then those in B<CApath>. Certificate matching 51112857Sdesis done based on the subject name, the key identifier (if present), and the 52112857Sdesserial number as taken from the certificate to be verified. If these data 53112857Sdesdo not match, the next certificate will be tried. If a first certificate 54112857Sdesmatching the parameters is found, the verification process will be performed; 55113260Sdesno other certificates for the same parameters will be searched in case of 56112857Sdesfailure. 57112857Sdes 58112857SdesIn server mode, when requesting a client certificate, the server must send 59112857Sdesthe list of CAs of which it will accept client certificates. This list 60112857Sdesis not influenced by the contents of B<CAfile> or B<CApath> and must 61112857Sdesexplicitly be set using the 62112857SdesL<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)> 63112857Sdesfamily of functions. 64112857Sdes 65112857SdesWhen building its own certificate chain, an OpenSSL client/server will 66112857Sdestry to fill in missing certificates from B<CAfile>/B<CApath>, if the 67112857Sdescertificate chain was not explicitly specified (see 68112857SdesL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, 69112857SdesL<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>. 70112857Sdes 71112857Sdes=head1 WARNINGS 72112857Sdes 73112857SdesIf several CA certificates matching the name, key identifier, and serial 74113260Sdesnumber condition are available, only the first one will be examined. This 75113260Sdesmay lead to unexpected results if the same CA certificate is available 76113260Sdeswith different expiration dates. If a "certificate expired" verification 77113260Sdeserror occurs, no other certificate will be searched. Make sure to not 78113260Sdeshave expired certificates mixed with valid ones. 79112857Sdes 80112857Sdes=head1 EXAMPLES 81112857Sdes 82112857SdesGenerate a CA certificate file with descriptive text from the CA certificates 83112857Sdesca1.pem ca2.pem ca3.pem: 84112857Sdes 85112857Sdes #!/bin/sh 86112857Sdes rm CAfile.pem 87112857Sdes for i in ca1.pem ca2.pem ca3.pem ; do 88112857Sdes openssl x509 -in $i -text >> CAfile.pem 89112857Sdes done 90112857Sdes 91112857SdesPrepare the directory /some/where/certs containing several CA certificates 92112857Sdesfor use as B<CApath>: 93113260Sdes 94113260Sdes cd /some/where/certs 95113260Sdes c_rehash . 96113260Sdes 97114262Sdes=head1 RETURN VALUES 98112857Sdes 99112857SdesThe following return values can occur: 100112857Sdes 101112857Sdes=over 4 102112857Sdes 103112857Sdes=item Z<>0 104112857Sdes 105112857SdesThe operation failed because B<CAfile> and B<CApath> are NULL or the 106112857Sdesprocessing at one of the locations specified failed. Check the error 107112857Sdesstack to find out the reason. 108112857Sdes 109112857Sdes=item Z<>1 110 111The operation succeeded. 112 113=back 114 115=head1 SEE ALSO 116 117L<ssl(3)|ssl(3)>, 118L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, 119L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, 120L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, 121L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, 122L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)> 123 124=cut 125