Document X509_LOOKUP_store

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

2 files changed, 53 insertions, 14 deletions

diff --git a/doc/man3/X509_LOOKUP_hash_dir.pod b/doc/man3/X509_LOOKUP_hash_dir.pod
index a9b837a308..30fbda8e03 100644
--- a/doc/man3/X509_LOOKUP_hash_dir.pod
+++ b/doc/man3/X509_LOOKUP_hash_dir.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-X509_LOOKUP_hash_dir, X509_LOOKUP_file,
+X509_LOOKUP_hash_dir, X509_LOOKUP_file, X509_LOOKUP_store,
 X509_load_cert_file,
 X509_load_crl_file,
 X509_load_cert_crl_file - Default OpenSSL certificate
@@ -14,6 +14,7 @@ lookup methods
 
  X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void);
  X509_LOOKUP_METHOD *X509_LOOKUP_file(void);
+ X509_LOOKUP_METHOD *X509_LOOKUP_store(void);
 
  int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type);
  int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type);
@@ -111,10 +112,24 @@ Note that the hash algorithm used for subject name hashing changed in OpenSSL
 OpenSSL includes a L<rehash(1)> utility which creates symlinks with correct
 hashed names for all files with .pem suffix in a given directory.
 
+=head2 OSSL_STORE Method
+
+B<X509_LOOKUP_store> is a method that allows access to any store of
+certificates and CRLs through any loader supported by
+L<OSSL_STORE(3)>.
+It works with the help of URIs, which can be direct references to
+certificates or CRLs, but can also be references to catalogues of such
+objects (that behave like directories).
+
+This method overlaps the L</File Method> and L</Hashed Directory Method>
+because of the 'file:' scheme loader.
+It does no caching of its own, but can use a caching L<OSSL_STORE(3)>
+loader, and therefore depends on the loader's capability.
+
 =head1 RETURN VALUES
 
-X509_LOOKUP_hash_dir() and X509_LOOKUP_file() always return a valid
-B<X509_LOOKUP_METHOD> structure.
+X509_LOOKUP_hash_dir(), X509_LOOKUP_file() and X509_LOOKUP_store()
+always return a valid B<X509_LOOKUP_METHOD> structure.
 
 X509_load_cert_file(), X509_load_crl_file() and X509_load_cert_crl_file() return
 the number of loaded objects or 0 on error.
@@ -126,10 +141,15 @@ L<X509_STORE_load_locations(3)>,
 L<X509_store_add_lookup(3)>,
 L<SSL_CTX_load_verify_locations(3)>,
 L<X509_LOOKUP_meth_new(3)>,
+L<OSSL_STORE(3)>
+
+=head1 HISTORY
+
+B<X509_LOOKUP_store> was added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2019 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/X509_STORE_add_cert.pod b/doc/man3/X509_STORE_add_cert.pod
index c0940b96ed..dd3d389e22 100644
--- a/doc/man3/X509_STORE_add_cert.pod
+++ b/doc/man3/X509_STORE_add_cert.pod
@@ -4,8 +4,9 @@
 
 X509_STORE_add_cert, X509_STORE_add_crl, X509_STORE_set_depth,
 X509_STORE_set_flags, X509_STORE_set_purpose, X509_STORE_set_trust,
-X509_STORE_load_locations,
-X509_STORE_set_default_paths
+X509_STORE_load_file, X509_STORE_load_path, X509_STORE_load_store,
+X509_STORE_set_default_paths,
+X509_STORE_load_locations
 - X509_STORE manipulation
 
 =head1 SYNOPSIS
@@ -19,9 +20,15 @@ X509_STORE_set_default_paths
  int X509_STORE_set_purpose(X509_STORE *ctx, int purpose);
  int X509_STORE_set_trust(X509_STORE *ctx, int trust);
 
+ int X509_STORE_set_default_paths(X509_STORE *ctx);
+ int X509_STORE_load_file(X509_STORE *ctx, const char *file);
+ int X509_STORE_load_path(X509_STORE *ctx, const char *dir);
+ int X509_STORE_load_store(X509_STORE *ctx, const char *uri);
+
+Deprecated:
+
  int X509_STORE_load_locations(X509_STORE *ctx,
                                const char *file, const char *dir);
- int X509_STORE_set_default_paths(X509_STORE *ctx);
 
 =head1 DESCRIPTION
 
@@ -65,11 +72,21 @@ for the corresponding values used in certificate chain validation.  Their
 behavior is documented in the corresponding B<X509_VERIFY_PARAM> manual
 pages, e.g., L<X509_VERIFY_PARAM_set_depth(3)>.
 
-X509_STORE_load_locations() loads trusted certificate(s) into an
-B<X509_STORE> from a given file and/or directory path.  It is permitted
-to specify just a file, just a directory, or both paths.  The certificates
-in the directory must be in hashed form, as documented in
-L<X509_LOOKUP_hash_dir(3)>.
+X509_STORE_load_file() loads trusted certificate(s) into an
+B<X509_STORE> from a given file.
+
+X509_STORE_load_path() loads trusted certificate(s) into an
+B<X509_STORE> from a given directory path.
+The certificates in the directory must be in hashed form, as
+documented in L<X509_LOOKUP_hash_dir(3)>.
+
+X509_STORE_load_store() loads trusted certificate(s) into an
+B<X509_STORE> from a store at a given URI.
+
+X509_STORE_load_locations() combines X509_STORE_load_file() and
+X509_STORE_load_dir() for a given file and/or directory path.
+It is permitted to specify just a file, just a directory, or both
+paths.
 
 X509_STORE_set_default_paths() is somewhat misnamed, in that it does not
 set what default paths should be used for loading certificates.  Instead,
@@ -80,8 +97,10 @@ paths.
 
 X509_STORE_add_cert(), X509_STORE_add_crl(), X509_STORE_set_depth(),
 X509_STORE_set_flags(), X509_STORE_set_purpose(),
-X509_STORE_set_trust(), X509_STORE_load_locations(), and
-X509_STORE_set_default_paths() return 1 on success or 0 on failure.
+X509_STORE_set_trust(), X509_STORE_load_file(),
+X509_STORE_load_path(), X509_STORE_load_store(),
+X509_STORE_load_locations(), and X509_STORE_set_default_paths() return
+1 on success or 0 on failure.
 
 =head1 SEE ALSO