Expand SSL_CTX_set_default_verify_paths() documentation

[openssl.git] / doc / ssl / SSL_CTX_load_verify_locations.pod

diff --git a/doc/ssl/SSL_CTX_load_verify_locations.pod b/doc/ssl/SSL_CTX_load_verify_locations.pod
index ed6aa6bc84628175d3b4af1862f4fe23d9c967c7..59d11e03ee4d0fb6f566fc58c6bb8f5dfd81c414 100644 (file)
--- a/doc/ssl/SSL_CTX_load_verify_locations.pod
+++ b/doc/ssl/SSL_CTX_load_verify_locations.pod
@@ -2,8 +2,9 @@
 
 =head1 NAME
 
 
 =head1 NAME
 

-SSL_CTX_load_verify_locations - set default locations for trusted CA
-certificates
+SSL_CTX_load_verify_locations, SSL_CTX_set_default_verify_paths,
+SSL_CTX_set_default_verify_dir, SSL_CTX_set_default_verify_file - set
+default locations for trusted CA certificates

 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 


@@ -12,12 +13,34 @@ certificates
  int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
                                    const char *CApath);
 
  int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
                                    const char *CApath);
 

+ int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx);
+
+ int SSL_CTX_set_default_verify_dir(SSL_CTX *ctx);
+
+ int SSL_CTX_set_default_verify_file(SSL_CTX *ctx);
+

 =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 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.
 

+SSL_CTX_set_default_verify_paths() specifies that the default locations from
+which CA certificates are loaded should be used. There is one default directory
+and one default file. The default CA certificates directory is called "certs" in
+the default OpenSSL directory. Alternatively the SSL_CERT_DIR environment
+variable can be defined to override this location. The default CA certificates
+file is called "cert.pem" in the default OpenSSL directory. Alternatively the
+SSL_CERT_FILE environment variable can be defined to override this location.
+
+SSL_CTX_set_default_verify_dir() is similar to
+SSL_CTX_set_default_verify_paths() except that just the default directory is
+used.
+
+SSL_CTX_set_default_verify_file() is similar to
+SSL_CTX_set_default_verify_paths() except that just the default file is
+used.
+

 =head1 NOTES
 
 If B<CAfile> is not NULL, it points to a file of CA certificates in PEM
 =head1 NOTES
 
 If B<CAfile> is not NULL, it points to a file of CA certificates in PEM


@@ -58,15 +81,15 @@ failure.
 In server mode, when requesting a client certificate, the server must send
 the list of CAs of which it will accept client certificates. This list
 is not influenced by the contents of B<CAfile> or B<CApath> and must
 In server mode, when requesting a client certificate, the server must send
 the list of CAs of which it will accept client certificates. This list
 is not influenced by the contents of B<CAfile> or B<CApath> and must

-explicitely be set using the
-L<SSL_CTX_set_client_CA_list(3)|SSL_CTX_set_client_CA_list(3)>
+explicitly be set using the
+L<SSL_CTX_set_client_CA_list(3)>

 family of functions.
 
 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 explicitly specified (see
 family of functions.
 
 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 explicitly 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)>.
+L<SSL_CTX_add_extra_chain_cert(3)>,
+L<SSL_CTX_use_certificate(3)>.

 
 =head1 WARNINGS
 
 
 =head1 WARNINGS
 


@@ -96,29 +119,43 @@ for use as B<CApath>:
 
 =head1 RETURN VALUES
 
 
 =head1 RETURN VALUES
 

-The following return values can occur:
+For SSL_CTX_load_verify_locations the following return values can occur:

 
 =over 4
 
 
 =over 4
 

-=item 0
+=item Z<>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.
 
 
 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
+=item Z<>1

 
 The operation succeeded.
 
 =back
 
 
 The operation succeeded.
 
 =back
 

+SSL_CTX_set_default_verify_paths(), SSL_CTX_set_default_verify_dir() and
+SSL_CTX_set_default_verify_file() all return 1 on success or 0 on failure. A
+missing default location is still treated as a success.
+

 =head1 SEE ALSO
 
 =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)>,
-L<SSL_CTX_set_cert_store(3)|SSL_CTX_set_cert_store(3)>
+L<ssl(3)>,
+L<SSL_CTX_set_client_CA_list(3)>,
+L<SSL_get_client_CA_list(3)>,
+L<SSL_CTX_use_certificate(3)>,
+L<SSL_CTX_add_extra_chain_cert(3)>,
+L<SSL_CTX_set_cert_store(3)>,
+L<SSL_CTX_set_client_CA_list(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.

 
 =cut
 
 =cut