STORE: Add documentation on expecting specific infos

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

5 files changed, 98 insertions, 7 deletions

diff --git a/doc/man1/storeutl.pod b/doc/man1/storeutl.pod
index 74361a7630..5b4faf4a25 100644
--- a/doc/man1/storeutl.pod
+++ b/doc/man1/storeutl.pod
@@ -15,6 +15,9 @@ B<openssl> B<storeutl>
 [B<-text arg>]
 [B<-engine id>]
 [B<-r>]
+[B<-certs>]
+[B<-keys>]
+[B<-crls>]
 B<uri> ...
 
 =head1 DESCRIPTION
@@ -60,6 +63,16 @@ The engine will then be set as the default for all available algorithms.
 
 Fetch objects recursively when possible.
 
+=item B<-certs>
+
+=item B<-keys>
+
+=item B<-crls>
+
+Only select the certificates, keys or CRLs from the given URI.
+However, if this URI would return a set of names (URIs), those are always
+returned.
+
 =back
 
 =head1 SEE ALSO
@@ -72,7 +85,7 @@ B<openssl> B<storeutl> was added to OpenSSL 1.1.1.
 
 =head1 COPYRIGHT
 
-Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-2018 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
diff --git a/doc/man3/OSSL_STORE_LOADER.pod b/doc/man3/OSSL_STORE_LOADER.pod
index 0bdd1124b6..aa64f2d773 100644
--- a/doc/man3/OSSL_STORE_LOADER.pod
+++ b/doc/man3/OSSL_STORE_LOADER.pod
@@ -5,10 +5,12 @@
 OSSL_STORE_LOADER, OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new,
 OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme,
 OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_ctrl,
+OSSL_STORE_LOADER_set_expect,
 OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof,
 OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close,
 OSSL_STORE_LOADER_free, OSSL_STORE_register_loader,
 OSSL_STORE_unregister_loader, OSSL_STORE_open_fn, OSSL_STORE_ctrl_fn,
+OSSL_STORE_expect_fn,
 OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn,
 OSSL_STORE_close_fn - Types and functions to manipulate, register and
 unregister STORE loaders for different URI schemes
@@ -37,6 +39,9 @@ unregister STORE loaders for different URI schemes
                                    va_list args);
  int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader,
                                 OSSL_STORE_ctrl_fn store_ctrl_function);
+ typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected);
+ int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader,
+                                  OSSL_STORE_expect_fn expect_function);
  typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,
                                                 UI_METHOD *ui_method,
                                                 void *ui_data);
@@ -71,9 +76,9 @@ OSSL_STORE_close() for this scheme.
 B<OSSL_STORE_LOADER_CTX> is a type template, to be defined by each loader
 using B<struct ossl_store_loader_ctx_st { ... }>.
 
-B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>, B<OSSL_STORE_load_fn>,
-B<OSSL_STORE_eof_fn> and B<OSSL_STORE_close_fn> are the function pointer
-types used within a STORE loader.
+B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>, B<OSSL_STORE_expect_fn>,
+B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn> and B<OSSL_STORE_close_fn>
+are the function pointer types used within a STORE loader.
 The functions pointed at define the functionality of the given loader.
 
 =over 4
@@ -108,6 +113,15 @@ numbers.
 
 This function is expected to return 1 on success, 0 on error.
 
+=item B<OSSL_STORE_expect_fn>
+
+This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<OSSL_STORE_INFO>
+identity B<expected>, and is used to tell the loader what object type is
+expected.
+B<expected> may be zero to signify that no specific object type is expected.
+
+This function is expected to return 1 on success, 0 on error.
+
 =item B<OSSL_STORE_load_fn>
 
 This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<UI_METHOD>
@@ -161,6 +175,9 @@ B<store_loader>.
 OSSL_STORE_LOADER_set_ctrl() sets the control function for the
 B<store_loader>.
 
+OSSL_STORE_LOADER_set_expect() sets the expect function for the
+B<store_loader>.
+
 OSSL_STORE_LOADER_set_load() sets the loader function for the
 B<store_loader>.
 
@@ -186,9 +203,10 @@ The B<file:> scheme has built in support.
 =head1 RETURN VALUES
 
 The functions with the types B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>,
+B<OSSL_STORE_expect_fn>,
 B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn> and B<OSSL_STORE_close_fn> have the
-same return values as OSSL_STORE_open(), OSSL_STORE_load(), OSSL_STORE_eof() and
-OSSL_STORE_close(), respectively.
+same return values as OSSL_STORE_open(), OSSL_STORE_ctrl(), OSSL_STORE_expect(),
+OSSL_STORE_load(), OSSL_STORE_eof() and OSSL_STORE_close(), respectively.
 
 OSSL_STORE_LOADER_new() returns a pointer to a B<OSSL_STORE_LOADER> on success,
 or B<NULL> on failure.
diff --git a/doc/man3/OSSL_STORE_expect.pod b/doc/man3/OSSL_STORE_expect.pod
new file mode 100644
index 0000000000..ef97ec85c4
--- /dev/null
+++ b/doc/man3/OSSL_STORE_expect.pod
@@ -0,0 +1,58 @@
+=pod
+
+=head1 NAME
+
+OSSL_STORE_expect - Specify what object type is expected
+
+=head1 SYNOPSIS
+
+ #include <openssl/store.h>
+
+ int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type);
+
+=head1 DESCRIPTION
+
+OSSL_STORE_expect() helps applications filter what OSSL_STORE_load() returns
+by specifying a B<OSSL_STORE_INFO> type.
+For example, if C<file:/foo/bar/store.pem> contains several different objects
+and only the certificates are interesting, the application can simply say
+that it expects the type B<OSSL_STORE_INFO_CERT>.
+All known object types (see L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS>)
+except for B<OSSL_STORE_INFO_NAME> are supported.
+
+OSSL_STORE_expect() I<must> be called before the first OSSL_STORE_load()
+of a given session, or it will fail.
+
+=head1 NOTES
+
+If a more elaborate filter is required by the application, a better choice
+would be to use a post-processing function.
+See L<OSSL_STORE_open(3)> for more information.
+
+However, some loaders may take advantage of the knowledge of an expected type
+to make object retrieval more efficient, so if a single type is expected, this
+method is usually preferable.
+
+=head1 RETURN VALUES
+
+OSSL_STORE_expect() returns 1 on success, or 0 on failure.
+
+=head1 SEE ALSO
+
+L<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_load(3)>
+
+=head1 HISTORY
+
+OSSL_STORE_expect()
+was added to OpenSSL 1.1.1.
+
+=head1 COPYRIGHT
+
+Copyright 2018 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
diff --git a/doc/man7/ossl_store.pod b/doc/man7/ossl_store.pod
index 71cb27d07f..80debebafc 100644
--- a/doc/man7/ossl_store.pod
+++ b/doc/man7/ossl_store.pod
@@ -86,7 +86,8 @@ only).
 
 =head1 SEE ALSO
 
-L<OSSL_STORE_open(3)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>
+L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>,
+L<OSSL_STORE_open(3)>, L<OSSL_STORE_expect(3)>
 
 =head1 COPYRIGHT
 
diff --git a/util/private.num b/util/private.num
index 099a4f70a8..48665577c9 100644
--- a/util/private.num
+++ b/util/private.num
@@ -33,6 +33,7 @@ OSSL_STORE_LOADER                       datatype
 OSSL_STORE_LOADER_CTX                   datatype
 OSSL_STORE_close_fn                     datatype
 OSSL_STORE_ctrl_fn                      datatype
+OSSL_STORE_expect_fn                    datatype
 OSSL_STORE_eof_fn                       datatype
 OSSL_STORE_error_fn                     datatype
 OSSL_STORE_load_fn                      datatype