OSSL_STORE: Make it possible to attach an OSSL_STORE to an opened BIO

This capability existed internally, and is now made public.

Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
(Merged from https://github.com/openssl/openssl/pull/11756)

2 files changed, 69 insertions, 5 deletions

diff --git a/doc/man3/OSSL_STORE_LOADER.pod b/doc/man3/OSSL_STORE_LOADER.pod
index 101857d543..97fde1268f 100644
--- a/doc/man3/OSSL_STORE_LOADER.pod
+++ b/doc/man3/OSSL_STORE_LOADER.pod
@@ -4,12 +4,14 @@
 
 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_find,
-OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof,
-OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close,
+OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_attach,
+OSSL_STORE_LOADER_set_ctrl, OSSL_STORE_LOADER_set_expect,
+OSSL_STORE_LOADER_set_find, 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_unregister_loader,
+OSSL_STORE_open_fn, OSSL_STORE_attach_fn, OSSL_STORE_ctrl_fn,
 OSSL_STORE_expect_fn, OSSL_STORE_find_fn,
 OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn,
 OSSL_STORE_close_fn - Types and functions to manipulate, register and
@@ -35,6 +37,16 @@ unregister STORE loaders for different URI schemes
                                                       void *ui_data);
  int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *store_loader,
                                 OSSL_STORE_open_fn store_open_function);
+ typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_attach_fn)(const OSSL_STORE_LOADER
+                                                        *loader,
+                                                        BIO *bio,
+                                                        OPENSSL_CTX *libctx,
+                                                        const char *propq,
+                                                        const UI_METHOD
+                                                        *ui_method,
+                                                        void *ui_data);
+ int OSSL_STORE_LOADER_set_attach(OSSL_STORE_LOADER *loader,
+                                  OSSL_STORE_attach_fn attach_function);
  typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd,
                                    va_list args);
  int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *store_loader,
@@ -99,6 +111,10 @@ initialized, to create a private data store (B<OSSL_STORE_LOADER_CTX>, see
 above), and to return it.
 If something goes wrong, this function is expected to return NULL.
 
+=item B<OSSL_STORE_open_fn>
+
+This function takes a B<BIO>, otherwise works like B<OSSL_STORE_open_fn>.
+
 =item B<OSSL_STORE_ctrl_fn>
 
 This function takes a B<OSSL_STORE_LOADER_CTX> pointer, a command number
@@ -189,6 +205,9 @@ OSSL_STORE_LOADER_get0_scheme() returns the scheme of the B<store_loader>.
 OSSL_STORE_LOADER_set_open() sets the opener function for the
 B<store_loader>.
 
+OSSL_STORE_LOADER_set_attach() sets the attacher function for the
+B<store_loader>.
+
 OSSL_STORE_LOADER_set_ctrl() sets the control function for the
 B<store_loader>.
 
diff --git a/doc/man3/OSSL_STORE_attach.pod b/doc/man3/OSSL_STORE_attach.pod
new file mode 100644
index 0000000000..7df2804964
--- /dev/null
+++ b/doc/man3/OSSL_STORE_attach.pod
@@ -0,0 +1,45 @@
+=pod
+
+=head1 NAME
+
+OSSL_STORE_attach - Functions to read objects from a BIO
+
+=head1 SYNOPSIS
+
+ #include <openssl/store.h>
+
+ OSSL_STORE_CTX *OSSL_STORE_attach(BIO *bio, OPENSSL_CTX *libctx,
+                                   const char *scheme, const char *propq,
+                                   const UI_METHOD *ui_method, void *ui_data,
+                                   OSSL_STORE_post_process_info_fn post_process,
+                                   void *post_process_data);
+
+=head1 DESCRIPTION
+
+OSSL_STORE_attach() works like L<OSSL_STORE_open(3)>, except it takes a B<BIO>
+I<bio> instead of a I<uri>, along with a I<scheme> to determine what loader
+should be used to process the data.
+
+=head1 RETURN VALUES
+
+OSSL_STORE_attach() returns a pointer to a B<OSSL_STORE_CTX> on success, or
+NULL on failure.
+
+=head1 SEE ALSO
+
+L<ossl_store(7)>, L<OSSL_STORE_open(3)>
+
+=head1 HISTORY
+
+OSSL_STORE_attach() was added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2020 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
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut