provider: add an unquery function to allow providers to clean up.

Without this, a provider  has no way to know that an application
has finished with the array it returned earlier.  A non-caching provider
requires this information.

Fixes #12974

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/12974)

3 files changed, 26 insertions, 3 deletions

diff --git a/doc/internal/man3/ossl_provider_new.pod b/doc/internal/man3/ossl_provider_new.pod
index d74ce57fef..40a2ebe7e3 100644
--- a/doc/internal/man3/ossl_provider_new.pod
+++ b/doc/internal/man3/ossl_provider_new.pod
@@ -13,7 +13,8 @@ ossl_provider_name, ossl_provider_dso,
 ossl_provider_module_name, ossl_provider_module_path,
 ossl_provider_libctx,
 ossl_provider_teardown, ossl_provider_gettable_params,
-ossl_provider_get_params, ossl_provider_query_operation,
+ossl_provider_get_params,
+ossl_provider_query_operation, ossl_provider_unquery_operation,
 ossl_provider_set_operation_bit, ossl_provider_test_operation_bit,
 ossl_provider_get_capabilities
 - internal provider routines
@@ -72,6 +73,9 @@ ossl_provider_get_capabilities
  const OSSL_ALGORITHM *ossl_provider_query_operation(const OSSL_PROVIDER *prov,
                                                      int operation_id,
                                                      int *no_cache);
+ void ossl_provider_unquery_operation(const OSSL_PROVIDER *prov,
+                                      int operation_id,
+                                      const OSSL_ALGORITHM *algs);
 
  int ossl_provider_set_operation_bit(OSSL_PROVIDER *provider, size_t bitnum);
  int ossl_provider_test_operation_bit(OSSL_PROVIDER *provider, size_t bitnum,
@@ -234,6 +238,10 @@ I<query_operation> function, if the provider has one.
 It should return an array of I<OSSL_ALGORITHM> for the given
 I<operation_id>.
 
+ossl_provider_unquery_operation() informs the provider that the result of
+ossl_provider_query_operation() is no longer going to be directly accessed and
+that all relevant information has been copied.
+
 ossl_provider_set_operation_bit() registers a 1 for operation I<bitnum>
 in a bitstring that's internal to I<provider>.
 
diff --git a/doc/man3/OSSL_PROVIDER.pod b/doc/man3/OSSL_PROVIDER.pod
index e5c451259a..d5317ee3f5 100644
--- a/doc/man3/OSSL_PROVIDER.pod
+++ b/doc/man3/OSSL_PROVIDER.pod
@@ -6,8 +6,8 @@ OSSL_PROVIDER_set_default_search_path,
 OSSL_PROVIDER, OSSL_PROVIDER_load, OSSL_PROVIDER_try_load, OSSL_PROVIDER_unload,
 OSSL_PROVIDER_available, OSSL_PROVIDER_do_all,
 OSSL_PROVIDER_gettable_params, OSSL_PROVIDER_get_params,
-OSSL_PROVIDER_query_operation, OSSL_PROVIDER_get0_provider_ctx,
-OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name,
+OSSL_PROVIDER_query_operation, OSSL_PROVIDER_unquery_operation,
+OSSL_PROVIDER_get0_provider_ctx, OSSL_PROVIDER_add_builtin, OSSL_PROVIDER_name,
 OSSL_PROVIDER_get_capabilities, OSSL_PROVIDER_self_test
 - provider routines
 
@@ -35,6 +35,9 @@ OSSL_PROVIDER_get_capabilities, OSSL_PROVIDER_self_test
  const OSSL_ALGORITHM *OSSL_PROVIDER_query_operation(const OSSL_PROVIDER *prov,
                                                      int operation_id,
                                                      int *no_cache);
+ void OSSL_PROVIDER_unquery_operation(const OSSL_PROVIDER *prov,
+                                      int operation_id,
+                                      const OSSL_ALGORITHM *algs);
  void *OSSL_PROVIDER_get0_provider_ctx(const OSSL_PROVIDER *prov);
 
  int OSSL_PROVIDER_add_builtin(OSSL_LIB_CTX *libctx, const char *name,
@@ -119,6 +122,10 @@ array of I<OSSL_ALGORITHM> for the given I<operation_id> terminated by an all
 NULL OSSL_ALGORITHM entry. This is considered a low-level function that most
 applications should not need to call.
 
+OSSL_PROVIDER_unquery_operation() calls the provider's I<unquery_operation>
+function (see L<provider(7)>), if the provider has one.  This is considered a
+low-level function that most applications should not need to call.
+
 OSSL_PROVIDER_get0_provider_ctx() returns the provider context for the given
 provider. The provider context is an opaque handle set by the provider itself
 and is passed back to the provider by libcrypto in various function calls.
diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod
index 8659431437..3b4416dac0 100644
--- a/doc/man7/provider-base.pod
+++ b/doc/man7/provider-base.pod
@@ -86,6 +86,8 @@ provider-base
  const OSSL_ALGORITHM *provider_query_operation(void *provctx,
                                                 int operation_id,
                                                 const int *no_store);
+ void provider_unquery_operation(void *provctx, int operation_id,
+                                 const OSSL_ALGORITHM *algs);
  const OSSL_ITEM *provider_get_reason_strings(void *provctx);
  int provider_get_capabilities(void *provctx, const char *capability,
                                OSSL_CALLBACK *cb, void *arg);
@@ -154,6 +156,7 @@ F<libcrypto>):
  provider_gettable_params       OSSL_FUNC_PROVIDER_GETTABLE_PARAMS
  provider_get_params            OSSL_FUNC_PROVIDER_GET_PARAMS
  provider_query_operation       OSSL_FUNC_PROVIDER_QUERY_OPERATION
+ provider_unquery_operation     OSSL_FUNC_PROVIDER_UNQUERY_OPERATION
  provider_get_reason_strings    OSSL_FUNC_PROVIDER_GET_REASON_STRINGS
  provider_get_capabilities      OSSL_FUNC_PROVIDER_GET_CAPABILITIES
  provider_self_test             OSSL_FUNC_PROVIDER_SELF_TEST
@@ -274,6 +277,11 @@ It should indicate if the core may store a reference to this array by
 setting I<*no_store> to 0 (core may store a reference) or 1 (core may
 not store a reference).
 
+provider_unquery_operation() informs the provider that the result of a
+provider_query_operation() is no longer directly required and that the function
+pointers have been copied.  The I<operation_id> should match that passed to
+provider_query_operation() and I<algs> should be its return value.
+
 provider_get_reason_strings() should return a constant B<OSSL_ITEM>
 array that provides reason strings for reason codes the provider may
 use when reporting errors using core_put_error().