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 3672613SkrisIf B<CApath> is not NULL, it points to a directory containing CA certificates 3772613Skrisin PEM format. The files each contain one CA certificate. The files are 3872613Skrislooked up by the CA subject name hash value, which must hence be available. 3972613SkrisIf more than one CA certificate with the same name hash value exist, the 4072613Skrisextension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search 4172613Skrisis performed in the ordering of the extension number, regardless of other 4272613Skrisproperties of the certificates. 4372613SkrisUse the B<c_rehash> utility to create the necessary links. 4472613Skris 4572613SkrisThe certificates in B<CApath> are only looked up when required, e.g. when 4672613Skrisbuilding the certificate chain or when actually performing the verification 4772613Skrisof a peer certificate. 4872613Skris 4972613SkrisWhen looking up CA certificates, the OpenSSL library will first search the 5072613Skriscertificates in B<CAfile>, then those in B<CApath>. Certificate matching 5172613Skrisis done based on the subject name, the key identifier (if present), and the 5272613Skrisserial number as taken from the certificate to be verified. If these data 5372613Skrisdo not match, the next certificate will be tried. If a first certificate 5472613Skrismatching the parameters is found, the verification process will be performed; 5572613Skrisno other certificates for the same parameters will be searched in case of 5672613Skrisfailure. 5772613Skris 5879998SkrisIn server mode, when requesting a client certificate, the server must send 5979998Skristhe list of CAs of which it will accept client certificates. This list 6079998Skrisis not influenced by the contents of B<CAfile> or B<CApath> and must 6189837Skrisexplicitly be set using the 6279998SkrisL<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)> 6379998Skrisfamily of functions. 6479998Skris 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 103267285Sjkim=item Z<>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 109267285Sjkim=item Z<>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)>, 12189837SkrisL<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, 12289837SkrisL<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)> 12372613Skris 12472613Skris=cut 125