diff options
author | kris <kris@FreeBSD.org> | 2001-02-18 03:17:36 +0000 |
---|---|---|
committer | kris <kris@FreeBSD.org> | 2001-02-18 03:17:36 +0000 |
commit | 7e55354aa4b06dead79c8a2c91756d71c0f02030 (patch) | |
tree | 5058ee297163944bfec8dbad8c8cad174f437d82 /crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod | |
parent | 539b977eff7c71f628cb2a407543a51070b14763 (diff) | |
download | FreeBSD-src-7e55354aa4b06dead79c8a2c91756d71c0f02030.zip FreeBSD-src-7e55354aa4b06dead79c8a2c91756d71c0f02030.tar.gz |
Import of OpenSSL 0.9.6-STABLE snapshot dated 2001-02-10
Diffstat (limited to 'crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod')
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod b/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod new file mode 100644 index 0000000..0e2d217 --- /dev/null +++ b/crypto/openssl/doc/ssl/SSL_CTX_load_verify_locations.pod @@ -0,0 +1,124 @@ +=pod + +=head1 NAME + +SSL_CTX_load_verify_locations - set default locations for trusted CA +certificates + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile, + const char *CApath); + +=head1 DESCRIPTION + +SSL_CTX_load_verify_locations() specifies the locations for B<ctx>, at +which CA certificates for verification purposes are located. The certificates +available via B<CAfile> and B<CApath> are trusted. + +=head1 NOTES + +If B<CAfile> is not NULL, it points to a file of CA certificates in PEM +format. The file can contain several CA certificates identified by + + -----BEGIN CERTIFICATE----- + ... (CA certificate in base64 encoding) ... + -----END CERTIFICATE----- + +sequences. Before, between, and after the certificates text is allowed +which can be used e.g. for descriptions of the certificates. + +The B<CAfile> is processed on execution of the SSL_CTX_load_verify_locations() +function. + +If on an TLS/SSL server no special setting is perfomed using *client_CA_list() +functions, the certificates contained in B<CAfile> are listed to the client +as available CAs during the TLS/SSL handshake. + +If B<CApath> is not NULL, it points to a directory containing CA certificates +in PEM format. The files each contain one CA certificate. The files are +looked up by the CA subject name hash value, which must hence be available. +If more than one CA certificate with the same name hash value exist, the +extension must be different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search +is performed in the ordering of the extension number, regardless of other +properties of the certificates. +Use the B<c_rehash> utility to create the necessary links. + +The certificates in B<CApath> are only looked up when required, e.g. when +building the certificate chain or when actually performing the verification +of a peer certificate. + +On a server, the certificates in B<CApath> are not listed as available +CA certificates to a client during a TLS/SSL handshake. + +When looking up CA certificates, the OpenSSL library will first search the +certificates in B<CAfile>, then those in B<CApath>. Certificate matching +is done based on the subject name, the key identifier (if present), and the +serial number as taken from the certificate to be verified. If these data +do not match, the next certificate will be tried. If a first certificate +matching the parameters is found, the verification process will be performed; +no other certificates for the same parameters will be searched in case of +failure. + +When building its own certificate chain, an OpenSSL client/server will +try to fill in missing certificates from B<CAfile>/B<CApath>, if the +certificate chain was not explicitely specified (see +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>. + +=head1 WARNINGS + +If several CA certificates matching the name, key identifier, and serial +number condition are available, only the first one will be examined. This +may lead to unexpected results if the same CA certificate is available +with different expiration dates. If a "certificate expired" verification +error occurs, no other certificate will be searched. Make sure to not +have expired certificates mixed with valid ones. + +=head1 EXAMPLES + +Generate a CA certificate file with descriptive text from the CA certificates +ca1.pem ca2.pem ca3.pem: + + #!/bin/sh + rm CAfile.pem + for i in ca1.pem ca2.pem ca3.pem ; do + openssl x509 -in $i -text >> CAfile.pem + done + +Prepare the directory /some/where/certs containing several CA certificates +for use as B<CApath>: + + cd /some/where/certs + c_rehash . + +=head1 RETURN VALUES + +The following return values can occur: + +=over 4 + +=item 0 + +The operation failed because B<CAfile> and B<CApath> are NULL or the +processing at one of the locations specified failed. Check the error +stack to find out the reason. + +=item 1 + +The operation succeeded. + +=back + +=head1 SEE ALSO + +L<ssl(3)|ssl(3)>, +L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>, +L<SSL_get_client_CA_list(3)|SSL_get_client_CA_list(3)>, +L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>, +L<SSL_CTX_add_extra_chain_cert(3)|SSL_CTX_add_extra_chain_cert(3)> + + +=cut |