Add provider documentation for the new open_ex

Signed-off-by: Simo Sorce <simo@redhat.com>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20131)

diff --git a/doc/man7/provider-storemgmt.pod b/doc/man7/provider-storemgmt.pod
index c58df619db9bc982b5080ab217d80a58cbf51a64..a8ce43c4bb2b5202789503d6d686abb3dccada9a 100644 (file)
--- a/doc/man7/provider-storemgmt.pod
+++ b/doc/man7/provider-storemgmt.pod
@@ -27,6 +27,10 @@ provider-storemgmt - The OSSL_STORE library E<lt>-E<gt> provider functions
  int OSSL_FUNC_store_export_object
      (void *loaderctx, const void *objref, size_t objref_sz,
       OSSL_CALLBACK *export_cb, void *export_cbarg);
+ void *OSSL_FUNC_store_open_ex(void *provctx, const char *uri,
+                               const OSSL_PARAM params[],
+                               OSSL_PASSPHRASE_CALLBACK *pw_cb,
+                               void *pw_cbarg);
 
  int OSSL_FUNC_store_delete(void *provctx, const char *uri,
                     const OSSL_PARAM params[],
@@ -75,6 +79,7 @@ in L<openssl-core_dispatch.h(7)>, as follows:
  OSSL_FUNC_store_close                OSSL_FUNC_STORE_CLOSE
  OSSL_FUNC_store_export_object        OSSL_FUNC_STORE_EXPORT_OBJECT
  OSSL_FUNC_store_delete               OSSL_FUNC_STORE_DELETE
+ OSSL_FUNC_store_open_ex              OSSL_FUNC_STORE_OPEN_EX
 
 =head2 Functions
 
@@ -124,6 +129,13 @@ implementation is entirely responsible for the interpretation of the URI.  In
 case a passphrase needs to be prompted to remove an object, I<pw_cb> should be
 called.
 
+OSSL_FUNC_store_open_ex() is an extended variant of OSSL_FUNC_store_open(). If
+the provider does not implement this function the code internally falls back to
+use the original OSSL_FUNC_store_open().
+This variant additionally accepts an L<OSSL_PARAM(3)> object and a I<pw_cb>
+callback that can be used to request a passphrase in cases where the whole
+store needs to be unlocked before performing any load operation.
+
 =head2 Load Parameters
 
 =over 4