KEYMGMT: Add key loading function OSSL_FUNC_keymgmt_load()

This function is used to create a keydata for a key that libcrypto
only has a reference to.

This introduces provider references, the contents which only the
provider know how to interpret.  Outside of the provider, this is just
an array of bytes.

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

5 files changed, 42 insertions, 7 deletions

diff --git a/crypto/evp/evp_local.h b/crypto/evp/evp_local.h
index 4aae702d6f..99c53484a6 100644
--- a/crypto/evp/evp_local.h
+++ b/crypto/evp/evp_local.h
@@ -122,6 +122,8 @@ struct evp_keymgmt_st {
     OSSL_FUNC_keymgmt_gen_fn *gen;
     OSSL_FUNC_keymgmt_gen_cleanup_fn *gen_cleanup;
 
+    OSSL_FUNC_keymgmt_load_fn *load;
+
     /* Key object checking */
     OSSL_FUNC_keymgmt_query_operation_name_fn *query_operation_name;
     OSSL_FUNC_keymgmt_has_fn *has;
diff --git a/crypto/evp/keymgmt_meth.c b/crypto/evp/keymgmt_meth.c
index 7847b98380..47067dd6c7 100644
--- a/crypto/evp/keymgmt_meth.c
+++ b/crypto/evp/keymgmt_meth.c
@@ -89,6 +89,10 @@ static void *keymgmt_from_dispatch(int name_id,
             if (keymgmt->free == NULL)
                 keymgmt->free = OSSL_FUNC_keymgmt_free(fns);
             break;
+        case OSSL_FUNC_KEYMGMT_LOAD:
+            if (keymgmt->load == NULL)
+                keymgmt->load = OSSL_FUNC_keymgmt_load(fns);
+            break;
         case OSSL_FUNC_KEYMGMT_GET_PARAMS:
             if (keymgmt->get_params == NULL) {
                 getparamfncnt++;
@@ -171,7 +175,9 @@ static void *keymgmt_from_dispatch(int name_id,
      * export if you can't import or export.
      */
     if (keymgmt->free == NULL
-        || (keymgmt->new == NULL && keymgmt->gen == NULL)
+        || (keymgmt->new == NULL
+            && keymgmt->gen == NULL
+            && keymgmt->load == NULL)
         || keymgmt->has == NULL
         || (getparamfncnt != 0 && getparamfncnt != 2)
         || (setparamfncnt != 0 && setparamfncnt != 2)
@@ -345,6 +351,14 @@ void evp_keymgmt_gen_cleanup(const EVP_KEYMGMT *keymgmt, void *genctx)
         keymgmt->gen_cleanup(genctx);
 }
 
+void *evp_keymgmt_load(const EVP_KEYMGMT *keymgmt,
+                       const void *objref, size_t objref_sz)
+{
+    if (keymgmt->load != NULL)
+        return keymgmt->load(objref, objref_sz);
+    return NULL;
+}
+
 int evp_keymgmt_get_params(const EVP_KEYMGMT *keymgmt, void *keydata,
                            OSSL_PARAM params[])
 {
diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod
index aa2be41acc..43743798ac 100644
--- a/doc/man7/provider-keymgmt.pod
+++ b/doc/man7/provider-keymgmt.pod
@@ -18,6 +18,7 @@ provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions
  void *OSSL_FUNC_keymgmt_new(void *provctx);
  void OSSL_FUNC_keymgmt_free(void *keydata);
 
+ /* Generation, a more complex constructor */
  void *OSSL_FUNC_keymgmt_gen_init(void *provctx, int selection);
  int OSSL_FUNC_keymgmt_gen_set_template(void *genctx, void *template);
  int OSSL_FUNC_keymgmt_gen_set_params(void *genctx, const OSSL_PARAM params[]);
@@ -25,6 +26,9 @@ provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions
  void *OSSL_FUNC_keymgmt_gen(void *genctx, OSSL_CALLBACK *cb, void *cbarg);
  void OSSL_FUNC_keymgmt_gen_cleanup(void *genctx);
 
+ /* Key loading by object reference, also a constructor */
+ void *OSSL_FUNC_keymgmt_load(const void *reference, size_t *reference_sz);
+
  /* Key object information */
  int OSSL_FUNC_keymgmt_get_params(void *keydata, OSSL_PARAM params[]);
  const OSSL_PARAM *OSSL_FUNC_keymgmt_gettable_params(void);
@@ -94,6 +98,8 @@ macros in L<openssl-core_dispatch.h(7)>, as follows:
  OSSL_FUNC_keymgmt_gen                  OSSL_FUNC_KEYMGMT_GEN
  OSSL_FUNC_keymgmt_gen_cleanup          OSSL_FUNC_KEYMGMT_GEN_CLEANUP
 
+ OSSL_FUNC_keymgmt_load                 OSSL_FUNC_KEYMGMT_LOAD
+
  OSSL_FUNC_keymgmt_get_params           OSSL_FUNC_KEYMGMT_GET_PARAMS
  OSSL_FUNC_keymgmt_gettable_params      OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS
  OSSL_FUNC_keymgmt_set_params           OSSL_FUNC_KEYMGMT_SET_PARAMS
@@ -209,8 +215,8 @@ OSSL_FUNC_keymgmt_free() should free the passed I<keydata>.
 
 OSSL_FUNC_keymgmt_gen_init(), OSSL_FUNC_keymgmt_gen_set_template(),
 OSSL_FUNC_keymgmt_gen_set_params(), OSSL_FUNC_keymgmt_gen_settable_params(),
-OSSL_FUNC_keymgmt_gen() and OSSL_FUNC_keymgmt_gen_cleanup() work together as a more
-elaborate context based key object constructor.
+OSSL_FUNC_keymgmt_gen() and OSSL_FUNC_keymgmt_gen_cleanup() work together as a
+more elaborate context based key object constructor.
 
 OSSL_FUNC_keymgmt_gen_init() should create the key object generation context
 and initialize it with I<selections>, which will determine what kind
@@ -238,10 +244,15 @@ progresses.
 OSSL_FUNC_keymgmt_gen_cleanup() should clean up and free the key object
 generation context I<genctx>
 
-At least one of OSSL_FUNC_keymgmt_new() and OSSL_FUNC_keymgmt_gen() are mandatory,
-as well as OSSL_FUNC_keymgmt_free().  Additionally, if OSSL_FUNC_keymgmt_gen() is
-present, OSSL_FUNC_keymgmt_gen_init() and OSSL_FUNC_keymgmt_gen_cleanup() must be
-present as well.
+OSSL_FUNC_keymgmt_load() creates a provider side key object based on a
+I<reference> object with a size of I<reference_sz> bytes, that only the
+provider knows how to interpret, but that may come from other operations.
+Outside the provider, this reference is simply an array of bytes.
+
+At least one of OSSL_FUNC_keymgmt_new(), OSSL_FUNC_keymgmt_gen() and
+OSSL_FUNC_keymgmt_load() are mandatory, as well as OSSL_FUNC_keymgmt_free().
+Additionally, if OSSL_FUNC_keymgmt_gen() is present, OSSL_FUNC_keymgmt_gen_init()
+and OSSL_FUNC_keymgmt_gen_cleanup() must be present as well.
 
 =head2 Key Object Information Functions
 
diff --git a/include/crypto/evp.h b/include/crypto/evp.h
index 2bd7a64e76..2e85b56266 100644
--- a/include/crypto/evp.h
+++ b/include/crypto/evp.h
@@ -713,6 +713,9 @@ void *evp_keymgmt_gen(const EVP_KEYMGMT *keymgmt, void *genctx,
                       OSSL_CALLBACK *cb, void *cbarg);
 void evp_keymgmt_gen_cleanup(const EVP_KEYMGMT *keymgmt, void *genctx);
 
+void *evp_keymgmt_load(const EVP_KEYMGMT *keymgmt,
+                       const void *objref, size_t objref_sz);
+
 int evp_keymgmt_has(const EVP_KEYMGMT *keymgmt, void *keyddata, int selection);
 int evp_keymgmt_validate(const EVP_KEYMGMT *keymgmt, void *keydata,
                          int selection);
diff --git a/include/openssl/core_dispatch.h b/include/openssl/core_dispatch.h
index 0feb38b417..efb05d404b 100644
--- a/include/openssl/core_dispatch.h
+++ b/include/openssl/core_dispatch.h
@@ -477,6 +477,11 @@ OSSL_CORE_MAKE_FUNC(void *, keymgmt_gen,
                     (void *genctx, OSSL_CALLBACK *cb, void *cbarg))
 OSSL_CORE_MAKE_FUNC(void, keymgmt_gen_cleanup, (void *genctx))
 
+/* Key loading by object reference */
+# define OSSL_FUNC_KEYMGMT_LOAD                        8
+OSSL_CORE_MAKE_FUNC(void *, keymgmt_load,
+                    (const void *reference, size_t reference_sz))
+
 /* Basic key object destruction */
 # define OSSL_FUNC_KEYMGMT_FREE                       10
 OSSL_CORE_MAKE_FUNC(void, keymgmt_free, (void *keydata))