From 631fb6af5f404e4f8b4ae33f3ffdcec81b9df19a Mon Sep 17 00:00:00 2001
From: Matt Caswell <matt@openssl.org>
Date: Tue, 22 Sep 2015 17:05:17 +0100
Subject: [PATCH] Document the default CA path functions

Reviewed-by: Andy Polyakov <appro@openssl.org>
---
 doc/ssl/SSL_CTX_load_verify_locations.pod | 24 ++++++++++++++++++++++-
 doc/ssl/ssl.pod                           | 11 +++++++++++
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/doc/ssl/SSL_CTX_load_verify_locations.pod b/doc/ssl/SSL_CTX_load_verify_locations.pod
index 8f7d627690..de388d3b50 100644
--- a/doc/ssl/SSL_CTX_load_verify_locations.pod
+++ b/doc/ssl/SSL_CTX_load_verify_locations.pod
@@ -12,12 +12,30 @@ certificates
  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.
 
+SSL_CTX_set_default_verify_paths() specifies that the default locations for
+which CA certificates are loaded should be used. There is one default directory
+and one default file.
+
+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
@@ -96,7 +114,7 @@ for use as B<CApath>:
 
 =head1 RETURN VALUES
 
-The following return values can occur:
+For SSL_CTX_load_verify_locations the following return values can occur:
 
 =over 4
 
@@ -112,6 +130,10 @@ 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
 
 L<ssl(3)>,
diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod
index 695a13c1c5..3466ee493d 100644
--- a/doc/ssl/ssl.pod
+++ b/doc/ssl/ssl.pod
@@ -298,6 +298,17 @@ protocol context defined in the B<SSL_CTX> structure.
 
 =item int B<SSL_CTX_set_default_verify_paths>(SSL_CTX *ctx);
 
+Use the default paths to locate trusted CA certificates. There is one default
+directory path and one default file path. Both are set via this call.
+
+=item int B<SSL_CTX_set_default_verify_dir>(SSL_CTX *ctx)
+
+Use the default directory path to locate trusted CA certficates.
+
+=item int B<SSL_CTX_set_default_verify_file>(SSL_CTX *ctx)
+
+Use the file path to locate trusted CA certficates.
+
 =item int B<SSL_CTX_set_ex_data>(SSL_CTX *s, int idx, char *arg);
 
 =item void B<SSL_CTX_set_info_callback>(SSL_CTX *ctx, void (*cb)(SSL *ssl, int cb, int ret));
-- 
2.25.1