Add OSSL_FUNC_keymgmt_im/export_types function that gets the provider context

The provider functions OSSL_FUNC_keymgmt_import_types() and
OSSL_FUNC_keymgmt_export_types() do not get the provider context passed.
This makes it difficult for providers to implement these functions unless
its a static implementation returning a truly constant OSSL_PARAM array.
Some providers may have a need to return an OSSL_PARAM array that is
dependent on the provider configuration, or anything else that is contained
in its provider context.

Add extended variants of these functions that get the provider context passed.
The functions should still return a static and constant OSSL_PARAM array, but
may use the provider context to select the array to return dependent on its
context. The returned array must be constant at least until the provider is
unloaded.

Providers can implement only the original functions, or only the extended
functions, or both. Implementing at least one of those functions is required
if also the respective OSSL_FUNC_keymgmt_import() or OSSL_FUNC_keymgmt_export()
function is implemented. If an extended function is available, it is called by
evp_keymgmt_import_types() or evp_keymgmt_export_types(), otherwise the original
function is called.

This makes the code backward compatible. Existing providers will only implement
the original functions, so these functions will continued to be called.
Newer providers can choose to implement the extended functions, and thus can
benefit from the provider context being passed to the implementation.

Signed-off-by: Ingo Franzki <ifranzki@linux.ibm.com>

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20255)

1 files changed, 24 insertions, 4 deletions

diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod
index 74516f44d1..430c2d465d 100644
--- a/doc/man7/provider-keymgmt.pod
+++ b/doc/man7/provider-keymgmt.pod
@@ -48,9 +48,11 @@ provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions
  /* Key object import and export functions */
  int OSSL_FUNC_keymgmt_import(void *keydata, int selection, const OSSL_PARAM params[]);
  const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types(int selection);
+ const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types_ex(void *provctx, int selection);
  int OSSL_FUNC_keymgmt_export(void *keydata, int selection,
                               OSSL_CALLBACK *param_cb, void *cbarg);
  const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection);
+ const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types_ex(void *provctx, int selection);
 
  /* Key object duplication, a constructor */
  void *OSSL_FUNC_keymgmt_dup(const void *keydata_from, int selection);
@@ -115,8 +117,10 @@ macros in L<openssl-core_dispatch.h(7)>, as follows:
 
  OSSL_FUNC_keymgmt_import               OSSL_FUNC_KEYMGMT_IMPORT
  OSSL_FUNC_keymgmt_import_types         OSSL_FUNC_KEYMGMT_IMPORT_TYPES
+ OSSL_FUNC_keymgmt_import_types_ex      OSSL_FUNC_KEYMGMT_IMPORT_TYPES_EX
  OSSL_FUNC_keymgmt_export               OSSL_FUNC_KEYMGMT_EXPORT
  OSSL_FUNC_keymgmt_export_types         OSSL_FUNC_KEYMGMT_EXPORT_TYPES
+ OSSL_FUNC_keymgmt_export_types_ex      OSSL_FUNC_KEYMGMT_EXPORT_TYPES_EX
 
  OSSL_FUNC_keymgmt_dup                  OSSL_FUNC_KEYMGMT_DUP
 
@@ -329,13 +333,25 @@ OSSL_FUNC_keymgmt_export() should extract values indicated by I<selection>
 from I<keydata>, create an L<OSSL_PARAM(3)> array with them and call
 I<param_cb> with that array as well as the given I<cbarg>.
 
-OSSL_FUNC_keymgmt_import_types() should return a constant array of descriptor
+OSSL_FUNC_keymgmt_import_types() and OSSL_FUNC_keymgmt_import_types_ex()
+should return a constant array of descriptor
 L<OSSL_PARAM(3)> for data indicated by I<selection>, for parameters that
 OSSL_FUNC_keymgmt_import() can handle.
-
-OSSL_FUNC_keymgmt_export_types() should return a constant array of descriptor
+Either OSSL_FUNC_keymgmt_import_types() or OSSL_FUNC_keymgmt_import_types_ex(),
+must be implemented, if OSSL_FUNC_keymgmt_import_types_ex() is implemented, then
+it is preferred over OSSL_FUNC_keymgmt_import_types().
+Providers that are supposed to be backward compatible with OpenSSL 3.0 or 3.1
+must continue to implement OSSL_FUNC_keymgmt_import_types().
+
+OSSL_FUNC_keymgmt_export_types() and OSSL_FUNC_keymgmt_export_types_ex()
+should return a constant array of descriptor
 L<OSSL_PARAM(3)> for data indicated by I<selection>, that the
 OSSL_FUNC_keymgmt_export() callback can expect to receive.
+Either OSSL_FUNC_keymgmt_export_types() or OSSL_FUNC_keymgmt_export_types_ex(),
+must be implemented, if OSSL_FUNC_keymgmt_export_types_ex() is implemented, then
+it is preferred over OSSL_FUNC_keymgmt_export_types().
+Providers that are supposed to be backward compatible with OpenSSL 3.0 or 3.1
+must continue to implement OSSL_FUNC_keymgmt_export_types().
 
 OSSL_FUNC_keymgmt_dup() should duplicate data subsets indicated by
 I<selection> or the whole key data I<keydata_from> and create a new
@@ -395,7 +411,8 @@ the requested operation, or NULL if the same name used to fetch the keymgmt
 applies.
 
 OSSL_FUNC_keymgmt_gettable_params() and OSSL_FUNC_keymgmt_settable_params()
-OSSL_FUNC_keymgmt_import_types(), OSSL_FUNC_keymgmt_export_types()
+OSSL_FUNC_keymgmt_import_types(), OSSL_FUNC_keymgmt_import_types_ex(),
+OSSL_FUNC_keymgmt_export_types(), OSSL_FUNC_keymgmt_export_types_ex()
 should
 always return a constant L<OSSL_PARAM(3)> array.
 
@@ -410,6 +427,9 @@ L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>
 
 The KEYMGMT interface was introduced in OpenSSL 3.0.
 
+Functions OSSL_FUNC_keymgmt_import_types_ex(), and OSSL_FUNC_keymgmt_export_types_ex()
+were added with OpenSSL 3.2.
+
 =head1 COPYRIGHT
 
 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.