Document added SSL functions related to X509_LOOKUP_store

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8442)

3 files changed, 43 insertions, 15 deletions

diff --git a/doc/man3/SSL_CTX_load_verify_locations.pod b/doc/man3/SSL_CTX_load_verify_locations.pod
index b955c60eed..3ee0f96345 100644
--- a/doc/man3/SSL_CTX_load_verify_locations.pod
+++ b/doc/man3/SSL_CTX_load_verify_locations.pod
@@ -2,36 +2,52 @@
 
 =head1 NAME
 
-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
+SSL_CTX_load_verify_dir, SSL_CTX_load_verify_file,
+SSL_CTX_load_verify_store, SSL_CTX_set_default_verify_paths,
+SSL_CTX_set_default_verify_dir, SSL_CTX_set_default_verify_file,
+SSL_CTX_set_default_verify_store, 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);
+ int SSL_CTX_load_verify_dir(SSL_CTX *ctx, const char *CApath);
+ int SSL_CTX_load_verify_file(SSL_CTX *ctx, const char *CAfile);
+ int SSL_CTX_load_verify_store(SSL_CTX *ctx, const char *CAstore);
 
  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);
+ int SSL_CTX_set_default_verify_store(SSL_CTX *ctx);
+
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
+ 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.
+SSL_CTX_load_verify_dir(), SSL_CTX_load_verify_file(),
+SSL_CTX_load_verify_store() specifies the locations for B<ctx>, at
+which CA certificates for verification purposes are located. The
+certificates available via B<CAfile>, B<CApath> and B<CAstore> 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.
+which CA certificates are loaded should be used. There is one default directory,
+one default file and one default store.
+The default CA certificates directory is called "certs" in the default OpenSSL
+directory, and this is also the default store.
+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
@@ -41,6 +57,10 @@ SSL_CTX_set_default_verify_file() is similar to
 SSL_CTX_set_default_verify_paths() except that just the default file is
 used.
 
+SSL_CTX_set_default_verify_store() is similar to
+SSL_CTX_set_default_verify_paths() except that just the default store is
+used.
+
 =head1 NOTES
 
 If B<CAfile> is not NULL, it points to a file of CA certificates in PEM
@@ -78,6 +98,11 @@ 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.
 
+If B<CAstore> is not NULL, it's a URI for to a store, which may
+represent a single container or a whole catalogue of containers.
+Apart from the B<CAstore> not necessarily being a local file or
+directory, it's generally treated the same way as a B<CApath>.
+
 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
diff --git a/util/missingmacro.txt b/util/missingmacro.txt
index 86142892a6..d42a26a6a2 100644
--- a/util/missingmacro.txt
+++ b/util/missingmacro.txt
@@ -194,7 +194,9 @@ X509_extract_key
 X509_REQ_extract_key
 X509_name_cmp
 X509_LOOKUP_load_file
+X509_LOOKUP_load_store
 X509_LOOKUP_add_dir
+X509_LOOKUP_add_store
 X509V3_conf_err
 X509V3_set_ctx_test
 X509V3_set_ctx_nodb
diff --git a/util/missingssl.txt b/util/missingssl.txt
index 3ee475d87a..be1e5f87b9 100644
--- a/util/missingssl.txt
+++ b/util/missingssl.txt
@@ -19,6 +19,7 @@ SSL_SRP_CTX_free
 SSL_SRP_CTX_init
 SSL_add_dir_cert_subjects_to_stack
 SSL_add_file_cert_subjects_to_stack
+SSL_add_store_cert_subjects_to_stack
 SSL_add_ssl_module
 SSL_certs_clear
 SSL_copy_session_id