From 504427eb5f32108dd64ff7858012863fe47b369b Mon Sep 17 00:00:00 2001

From: Simo Sorce <simo@redhat.com>

Date: Thu, 10 Nov 2022 16:58:28 -0500

Subject: [PATCH 2/3] Update documentation for keymgmt export utils

Change function prototypes and explain how to use the selection

argument.

Signed-off-by: Simo Sorce <simo@redhat.com>

Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>

Reviewed-by: Tomas Mraz <tomas@openssl.org>

(Merged from https://github.com/openssl/openssl/pull/19648)

diff --git a/doc/internal/man3/evp_keymgmt_util_export_to_provider.pod b/doc/internal/man3/evp_keymgmt_util_export_to_provider.pod

index 1fee9f6ff9..7099e44964 100644

--- a/doc/internal/man3/evp_keymgmt_util_export_to_provider.pod

+++ b/doc/internal/man3/evp_keymgmt_util_export_to_provider.pod

@@ -20,12 +20,14 @@ OP_CACHE_ELEM

  int evp_keymgmt_util_export(const EVP_PKEY *pk, int selection,

                              OSSL_CALLBACK *export_cb, void *export_cbarg);

- void *evp_keymgmt_util_export_to_provider(EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);

+ void *evp_keymgmt_util_export_to_provider(EVP_PKEY *pk, EVP_KEYMGMT *keymgmt,

+                                           int selection);

  OP_CACHE_ELEM *evp_keymgmt_util_find_operation_cache(EVP_PKEY *pk,

-                                                      EVP_KEYMGMT *keymgmt);

+                                                      EVP_KEYMGMT *keymgmt,

+                                                      int selection);

  int evp_keymgmt_util_clear_operation_cache(EVP_PKEY *pk, int locking);

- int evp_keymgmt_util_cache_keydata(EVP_PKEY *pk,

-                                    EVP_KEYMGMT *keymgmt, void *keydata);

+ int evp_keymgmt_util_cache_keydata(EVP_PKEY *pk, EVP_KEYMGMT *keymgmt,

+                                    void *keydata, int selection);

  void evp_keymgmt_util_cache_keyinfo(EVP_PKEY *pk);

  void *evp_keymgmt_util_fromdata(EVP_PKEY *target, EVP_KEYMGMT *keymgmt,

                                  int selection, const OSSL_PARAM params[]);

@@ -65,6 +67,11 @@ evp_keymgmt_util_fromdata() can be used to add key object data to a

 given key I<target> via a B<EVP_KEYMGMT> interface.  This is used as a

 helper for L<EVP_PKEY_fromdata(3)>.

+In all functions that take a I<selection> argument, the selection is used to

+constraint the information requested on export. It is also used in the cache

+so that key data is guaranteed to contain all the information requested in

+the selection.

+

 =head1 RETURN VALUES

 evp_keymgmt_export_to_provider() and evp_keymgmt_util_fromdata()

-- 

2.38.1