SSL_CTX_load_verify_locations.pod revision 76866
172613Skris=pod 272613Skris 372613Skris=head1 NAME 472613Skris 572613SkrisSSL_CTX_load_verify_locations - set default locations for trusted CA 672613Skriscertificates 772613Skris 872613Skris=head1 SYNOPSIS 972613Skris 1072613Skris #include <openssl/ssl.h> 1172613Skris 1272613Skris int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, 1372613Skris const char *CApath); 1472613Skris 1572613Skris=head1 DESCRIPTION 1672613Skris 1772613SkrisSSL_CTX_load_verify_locations() specifies the locations for B<ctx>, at 1872613Skriswhich CA certificates for verification purposes are located. The certificates 1972613Skrisavailable via B<CAfile> and B<CApath> are trusted. 2072613Skris 2172613Skris=head1 NOTES 2272613Skris 2372613SkrisIf B<CAfile> is not NULL, it points to a file of CA certificates in PEM 2472613Skrisformat. The file can contain several CA certificates identified by 2572613Skris 2672613Skris -----BEGIN CERTIFICATE----- 2772613Skris ... (CA certificate in base64 encoding) ... 2872613Skris -----END CERTIFICATE----- 2972613Skris 3072613Skrissequences. Before, between, and after the certificates text is allowed 3172613Skriswhich can be used e.g. for descriptions of the certificates. 3272613Skris 3372613SkrisThe B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations() 3472613Skrisfunction. 3572613Skris 3676866SkrisIf on an TLS/SSL server no special setting is performed using *client_CA_list() 3772613Skrisfunctions, the certificates contained in B<CAfile> are listed to the client 3872613Skrisas available CAs during the TLS/SSL handshake. 3972613Skris 4072613SkrisIf B<CApath> is not NULL, it points to a directory containing CA certificates 4172613Skrisin PEM format. The files each contain one CA certificate. The files are 4272613Skrislooked up by the CA subject name hash value, which must hence be available. 4372613SkrisIf more than one CA certificate with the same name hash value exist, the 4472613Skrisextension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search 4572613Skrisis performed in the ordering of the extension number, regardless of other 4672613Skrisproperties of the certificates. 4772613SkrisUse the B<c_rehash> utility to create the necessary links. 4872613Skris 4972613SkrisThe certificates in B<CApath> are only looked up when required, e.g. when 5072613Skrisbuilding the certificate chain or when actually performing the verification 5172613Skrisof a peer certificate. 5272613Skris 5372613SkrisOn a server, the certificates in B<CApath> are not listed as available 5472613SkrisCA certificates to a client during a TLS/SSL handshake. 5572613Skris 5672613SkrisWhen looking up CA certificates, the OpenSSL library will first search the 5772613Skriscertificates in B<CAfile>, then those in B<CApath>. Certificate matching 5872613Skrisis done based on the subject name, the key identifier (if present), and the 5972613Skrisserial number as taken from the certificate to be verified. If these data 6072613Skrisdo not match, the next certificate will be tried. If a first certificate 6172613Skrismatching the parameters is found, the verification process will be performed; 6272613Skrisno other certificates for the same parameters will be searched in case of 6372613Skrisfailure. 6472613Skris 6572613SkrisWhen building its own certificate chain, an OpenSSL client/server will 6672613Skristry to fill in missing certificates from B<CAfile>/B<CApath>, if the 6776866Skriscertificate chain was not explicitly specified (see 6872613SkrisL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, 6972613SkrisL<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>. 7072613Skris 7172613Skris=head1 WARNINGS 7272613Skris 7372613SkrisIf several CA certificates matching the name, key identifier, and serial 7472613Skrisnumber condition are available, only the first one will be examined. This 7572613Skrismay lead to unexpected results if the same CA certificate is available 7672613Skriswith different expiration dates. If a "certificate expired" verification 7772613Skriserror occurs, no other certificate will be searched. Make sure to not 7872613Skrishave expired certificates mixed with valid ones. 7972613Skris 8072613Skris=head1 EXAMPLES 8172613Skris 8272613SkrisGenerate a CA certificate file with descriptive text from the CA certificates 8372613Skrisca1.pem ca2.pem ca3.pem: 8472613Skris 8572613Skris #!/bin/sh 8672613Skris rm CAfile.pem 8772613Skris for i in ca1.pem ca2.pem ca3.pem ; do 8872613Skris openssl x509 -in $i -text >> CAfile.pem 8972613Skris done 9072613Skris 9172613SkrisPrepare the directory /some/where/certs containing several CA certificates 9272613Skrisfor use as B<CApath>: 9372613Skris 9472613Skris cd /some/where/certs 9572613Skris c_rehash . 9672613Skris 9772613Skris=head1 RETURN VALUES 9872613Skris 9972613SkrisThe following return values can occur: 10072613Skris 10172613Skris=over 4 10272613Skris 10372613Skris=item 0 10472613Skris 10572613SkrisThe operation failed because B<CAfile> and B<CApath> are NULL or the 10672613Skrisprocessing at one of the locations specified failed. Check the error 10772613Skrisstack to find out the reason. 10872613Skris 10972613Skris=item 1 11072613Skris 11172613SkrisThe operation succeeded. 11272613Skris 11372613Skris=back 11472613Skris 11572613Skris=head1 SEE ALSO 11672613Skris 11772613SkrisL<ssl(3)|ssl(3)>, 11872613SkrisL<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, 11972613SkrisL<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, 12072613SkrisL<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, 12172613SkrisL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> 12272613Skris 12372613Skris 12472613Skris=cut 125