diff options
author | Pauli <paul.dale@oracle.com> | 2020-09-25 10:19:19 +1000 |
---|---|---|
committer | Pauli <ppzgs1@gmail.com> | 2021-02-24 21:24:36 +1000 |
commit | b0001d0cf2539b9309712e3e04f407dcbb04352c (patch) | |
tree | fb7e81074c5d0ca84b3ae37f47bc612eb608b26e /doc | |
parent | 8b3facd7324b6c2f36f6414c0552da26378aae4a (diff) |
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)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/internal/man3/ossl_provider_new.pod | 10 | ||||
-rw-r--r-- | doc/man3/OSSL_PROVIDER.pod | 11 | ||||
-rw-r--r-- | doc/man7/provider-base.pod | 8 |
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(). |