Redesign the KEYMGMT libcrypto <-> provider interface - the basics

The KEYMGMT libcrypto <-> provider interface currently makes a few
assumptions:

1.  provider side domain parameters and key data isn't mutable. In
    other words, as soon as a key has been created in any (loaded,
    imported data, ...), it's set in stone.
2.  provider side domain parameters can be strictly separated from the
    key data.

This does work for the most part, but there are places where that's a
bit too rigid for the functionality that the EVP_PKEY API delivers.
Key data needs to be mutable to allow the flexibility that functions
like EVP_PKEY_copy_parameters promise, as well as to provide the
combinations of data that an EVP_PKEY is generally assumed to be able
to hold:

- domain parameters only
- public key only
- public key + private key
- domain parameters + public key
- domain parameters + public key + private key

To remedy all this, we:

1.  let go of the distinction between domain parameters and key
    material proper in the libcrypto <-> provider interface.

    As a consequence, functions that still need it gain a selection
    argument, which is a set of bits that indicate what parts of the
    key object are to be considered in a specific call.  This allows
    a reduction of very similar functions into one.

2.  Rework the libcrypto <-> provider interface so provider side key
    objects are created and destructed with a separate function, and
    get their data filled and extracted in through import and export.

(future work will see other key object constructors and other
functions to fill them with data)

Fixes #10979

squash! Redesign the KEYMGMT libcrypto <-> provider interface - the basics

Remedy 1 needs a rewrite:

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

11 files changed, 336 insertions, 315 deletions

diff --git a/doc/internal/man3/evp_keymgmt_export_to_provider.pod b/doc/internal/man3/evp_keymgmt_export_to_provider.pod
deleted file mode 100644
index 2cb40940b4..0000000000
--- a/doc/internal/man3/evp_keymgmt_export_to_provider.pod
+++ /dev/null
@@ -1,56 +0,0 @@
-=pod
-
-=head1 NAME
-
-evp_keymgmt_export_to_provider,
-evp_keymgmt_clear_pkey_cache
-- key material provider export for EVP
-
-=head1 SYNOPSIS
-
- #include "crypto/evp.h"
-
- void *evp_keymgmt_export_to_provider(EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);
- void evp_keymgmt_clear_pkey_cache(EVP_PKEY *pk);
-
-=head1 DESCRIPTION
-
-evp_keymgmt_export_to_provider() exports the key material from the
-given key I<pk> to a provider via a B<EVP_KEYMGMT> interface, if this
-hasn't already been done.
-It maintains a cache of provider key references in I<pk> to keep track
-of all such exports.
-
-If I<pk> has an assigned legacy key, a check is done to see if any of
-its key material has changed since last export, i.e. the legacy key's
-is_dirty() method returns 1.
-If it has, the cache of already exported keys is cleared, and a new
-export is made with the new key material.
-
-evp_keymgmt_clear_pkey_cache() can be used to explicitly clear the
-cache of provider key references.
-
-=head1 RETURN VALUES
-
-evp_keymgmt_export_to_provider() returns a pointer to the appropriate
-provider side key (created or found again), or NULL on error.
-
-=head1 NOTES
-
-"Legacy key" is the term used for any key that has been assigned to an
-B<EVP_PKEY> with EVP_PKEY_assign_RSA() and similar functions.
-
-=head1 SEE ALSO
-
-L<EVP_PKEY_ASN1_METHOD(3)>, L<EVP_PKEY_assign_RSA(3)>
-
-=head1 COPYRIGHT
-
-Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License").  You may not use
-this file except in compliance with the License.  You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
diff --git a/doc/internal/man3/evp_keymgmt_freekey.pod b/doc/internal/man3/evp_keymgmt_freekey.pod
deleted file mode 100644
index 8be73aee81..0000000000
--- a/doc/internal/man3/evp_keymgmt_freekey.pod
+++ /dev/null
@@ -1,109 +0,0 @@
-=pod
-
-=head1 NAME
-
-evp_keymgmt_importdomparams, evp_keymgmt_gendomparams,
-evp_keymgmt_freedomparams,
-evp_keymgmt_exportdomparams,
-evp_keymgmt_importdomparams_types, evp_keymgmt_exportdomparams_types,
-evp_keymgmt_importkey, evp_keymgmt_genkey, evp_keymgmt_loadkey,
-evp_keymgmt_freekey,
-evp_keymgmt_exportkey,
-evp_keymgmt_importkey_types, evp_keymgmt_exportkey_types
-- internal KEYMGMT support functions
-
-=head1 SYNOPSIS
-
- #include "crypto/evp.h"
-
- void *evp_keymgmt_importdomparams(const EVP_KEYMGMT *keymgmt,
-                                const OSSL_PARAM params[]);
- void *evp_keymgmt_gendomparams(const EVP_KEYMGMT *keymgmt,
-                             const OSSL_PARAM params[]);
- void evp_keymgmt_freedomparams(const EVP_KEYMGMT *keymgmt, void *provdomparams);
- int evp_keymgmt_exportdomparams(const EVP_KEYMGMT *keymgmt,
-                              void *provdomparams, OSSL_PARAM params[]);
- const OSSL_PARAM *evp_keymgmt_importdomparams_types(const EVP_KEYMGMT *keymgmt);
- const OSSL_PARAM *evp_keymgmt_exportdomparams_types(const EVP_KEYMGMT *keymgmt);
-
- void *evp_keymgmt_importkey(const EVP_KEYMGMT *keymgmt,
-                             const OSSL_PARAM params[]);
- void *evp_keymgmt_genkey(const EVP_KEYMGMT *keymgmt, void *domparams,
-                          const OSSL_PARAM params[]);
- void *evp_keymgmt_loadkey(const EVP_KEYMGMT *keymgmt,
-                           void *id, size_t idlen);
- void evp_keymgmt_freekey(const EVP_KEYMGMT *keymgmt, void *provkey);
- int evp_keymgmt_exportkey(const EVP_KEYMGMT *keymgmt, void *provkey,
-                           OSSL_PARAM params[]);
- const OSSL_PARAM *evp_keymgmt_importkey_types(const EVP_KEYMGMT *keymgmt);
- const OSSL_PARAM *evp_keymgmt_exportkey_types(const EVP_KEYMGMT *keymgmt);
-
-=head1 DESCRIPTION
-
-All these functions are helpers to call the provider's corresponding
-function.
-
-evp_keymgmt_importdomparams() calls the method's importdomparams() function.
-
-evp_keymgmt_gendomparams() calls the method's gendomparams() function.
-
-evp_keymgmt_freedomparams() calls the method's freedomparams() function.
-
-evp_keymgmt_exportdomparams() calls the method's exportdomparams()
-function.
-
-evp_keymgmt_importdomparams_types() calls the method's
-importdomparams_types() function.
-
-evp_keymgmt_exportdomparams_types() calls the method's
-exportdomparams_types() function.
-
-evp_keymgmt_importkey() calls the method's importkey()
-function.
-
-evp_keymgmt_genkey() calls the method's genkey() function.
-
-evp_keymgmt_loadkey() calls the method's loadkey() function.
-
-evp_keymgmt_freekey() calls the method's freekey() function.
-
-evp_keymgmt_exportkey() calls the method's exportkey()
-function.
-
-evp_keymgmt_importkey_types() calls the method's importkey_types() function.
-
-evp_keymgmt_exportkey_types() calls the method's exportkey_types() function.
-
-=head1 RETURN VALUES
-
-evp_keymgmt_importdomparams(), evp_keymgmt_gendomparams() return a pointer
-to a provider owned set of domparams parameters, or NULL on error.
-
-evp_keymgmt_importkey(), evp_keymgmt_genkey(), evp_keymgmt_loadkey() return
-a pointer to a provider owned key, or NULL on error.
-
-evp_keymgmt_exportdomparams() and evp_keymgmt_exportkey() return 1 on success,
-or 0 on error.
-
-evp_keymgmt_importdomparams_types(), evp_keymgmt_exportdomparams_types()
-return parameter descriptor for importing and exporting domparams
-parameters, or NULL if there are no such descriptors.
-
-evp_keymgmt_importkey_types() and evp_keymgmt_exportkey_types()
-return parameter descriptor for importing and exporting keys, or NULL
-if there are no such descriptors.
-
-=head1 HISTORY
-
-The functions described here were all added in OpenSSL 3.0.
-
-=head1 COPYRIGHT
-
-Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the Apache License 2.0 (the "License").  You may not use
-this file except in compliance with the License.  You can obtain a copy
-in the file LICENSE in the source distribution or at
-L<https://www.openssl.org/source/license.html>.
-
-=cut
diff --git a/doc/internal/man3/evp_keymgmt_newdata.pod b/doc/internal/man3/evp_keymgmt_newdata.pod
new file mode 100644
index 0000000000..861f57f7f5
--- /dev/null
+++ b/doc/internal/man3/evp_keymgmt_newdata.pod
@@ -0,0 +1,93 @@
+=pod
+
+=head1 NAME
+
+evp_keymgmt_newdata, evp_keymgmt_freedata,
+evp_keymgmt_get_params, evp_keymgmt_gettable_params,
+evp_keymgmt_has, evp_keymgmt_validate,
+evp_keymgmt_import, evp_keymgmt_import_types,
+evp_keymgmt_export, evp_keymgmt_export_types
+- internal KEYMGMT interface functions
+
+=head1 SYNOPSIS
+
+ #include "crypto/evp.h"
+
+ void *evp_keymgmt_newdata(const EVP_KEYMGMT *keymgmt);
+ void evp_keymgmt_freedata(const EVP_KEYMGMT *keymgmt, void *keyddata);
+ int evp_keymgmt_get_params(const EVP_KEYMGMT *keymgmt,
+                            void *keydata, OSSL_PARAM params[]);
+ const OSSL_PARAM *evp_keymgmt_gettable_params(const EVP_KEYMGMT *keymgmt);
+ 
+ 
+ int evp_keymgmt_has(const EVP_KEYMGMT *keymgmt, void *keyddata, int selection);
+ int evp_keymgmt_validate(const EVP_KEYMGMT *keymgmt, void *keydata,
+                          int selection);
+ 
+ int evp_keymgmt_import(const EVP_KEYMGMT *keymgmt, void *keydata,
+                        int selection, const OSSL_PARAM params[]);
+ const OSSL_PARAM *evp_keymgmt_import_types(const EVP_KEYMGMT *keymgmt,
+                                            int selection);
+ int evp_keymgmt_export(const EVP_KEYMGMT *keymgmt, void *keydata,
+                        int selection, OSSL_CALLBACK *param_cb, void *cbarg);
+ const OSSL_PARAM *evp_keymgmt_export_types(const EVP_KEYMGMT *keymgmt,
+                                            int selection);
+
+=head1 DESCRIPTION
+
+All these functions are helpers to call the provider's corresponding
+function.  They all have in common that they take a B<EVP_KEYMGMT> as
+first argument, which they also retrieve a provider context from when
+needed.  The rest of the arguments are simply passed on to the
+function they wrap around.
+
+evp_keymgmt_newdata() calls the method's new() function.
+
+evp_keymgmt_freedata() calls the method's free() function.
+
+(the name evp_keymgmt_freedata() was chosen to avoid a clash with
+EVP_KEYMGMT_free() on case insensitive systems, the name
+evp_keymgmt_newdata() was chosen for consistency)
+
+evp_keymgmt_get_params() calls the method's get_params() function.
+
+evp_keymgmt_gettable_params() calls the method's gettable_params()
+function.
+
+evp_keymgmt_has() calls the method's has() function.
+
+evp_keymgmt_validate() calls the method's validate() function.
+
+evp_keymgmt_import() calls the method's import() function.
+
+evp_keymgmt_import_types() calls the method's import_types() function.
+
+evp_keymgmt_export() calls the method's export() function.
+
+evp_keymgmt_export_types() calls the method's export_types() function.
+
+=head1 RETURN VALUES
+
+evp_keymgmt_newdata() returns a pointer to a provider side key object,
+or NULL on error.
+
+evp_keymgmt_gettable_params(), evp_keymgmt_import_types(), and
+evp_keymgmt_export_types() return parameter descriptor for importing
+and exporting key data, or NULL if there are no such descriptors.
+
+All other functions return 1 on success and 0 on error.
+
+=head1 HISTORY
+
+The functions described here were all added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/internal/man3/evp_keymgmt_util_export_to_provider.pod b/doc/internal/man3/evp_keymgmt_util_export_to_provider.pod
new file mode 100644
index 0000000000..38e71334c8
--- /dev/null
+++ b/doc/internal/man3/evp_keymgmt_util_export_to_provider.pod
@@ -0,0 +1,71 @@
+=pod
+
+=head1 NAME
+
+evp_keymgmt_util_export_to_provider,
+evp_keymgmt_util_clear_pkey_cache,
+evp_keymgmt_util_cache_pkey,
+evp_keymgmt_util_fromdata
+- internal KEYMGMT utility functions
+
+=head1 SYNOPSIS
+
+ #include "crypto/evp.h"
+
+ void *evp_keymgmt_util_export_to_provider(EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);
+ void evp_keymgmt_util_clear_pkey_cache(EVP_PKEY *pk);
+ void evp_keymgmt_util_cache_pkey(EVP_PKEY *pk, size_t index,
+                                  EVP_KEYMGMT *keymgmt, void *keydata);
+ void *evp_keymgmt_util_fromdata(EVP_PKEY *target, EVP_KEYMGMT *keymgmt,
+                                 int selection, const OSSL_PARAM params[]);
+
+=head1 DESCRIPTION
+
+evp_keymgmt_util_export_to_provider() exports the key material from
+the given key I<pk> to a provider via a B<EVP_KEYMGMT> interface, if
+this hasn't already been done.
+It maintains a cache of provider key references in I<pk> to keep track
+of all such exports.
+
+If I<pk> has an assigned legacy key, a check is done to see if any of
+its key material has changed since last export, i.e. the legacy key's
+is_dirty() method returns 1.
+If it has, the cache of already exported keys is cleared, and a new
+export is made with the new key material.
+
+evp_keymgmt_util_clear_pkey_cache() can be used to explicitly clear
+the cache of provider key references.
+
+evp_keymgmt_util_cache_pkey() can be used to assign a provider key
+object to a specific cache slot in the given I<target>.
+I<Use with extreme care>.
+
+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)>.
+
+=head1 RETURN VALUES
+
+evp_keymgmt_export_to_provider() and evp_keymgmt_util_fromdata()
+return a pointer to the appropriate provider side key (created or
+found again), or NULL on error.
+
+=head1 NOTES
+
+"Legacy key" is the term used for any key that has been assigned to an
+B<EVP_PKEY> with EVP_PKEY_assign_RSA() and similar functions.
+
+=head1 SEE ALSO
+
+L<EVP_PKEY_ASN1_METHOD(3)>, L<EVP_PKEY_assign_RSA(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/internal/man3/evp_pkey_make_provided.pod b/doc/internal/man3/evp_pkey_make_provided.pod
index e5dde78c4f..12cbe0c365 100644
--- a/doc/internal/man3/evp_pkey_make_provided.pod
+++ b/doc/internal/man3/evp_pkey_make_provided.pod
@@ -10,8 +10,7 @@ evp_pkey_make_provided - internal EVP_PKEY support functions for providers
  #include "evp_local.h"
 
  void *evp_pkey_make_provided(EVP_PKEY *pk, OPENSSL_CTX *libctx,
-                              EVP_KEYMGMT **keymgmt, const char *propquery,
-                              int domainparams);
+                              EVP_KEYMGMT **keymgmt, const char *propquery);
 
 =head1 DESCRIPTION
 
@@ -24,8 +23,6 @@ used for exporting.  If not (I<*keymgmt> is NULL), then this function will
 fetch an B<EVP_KEYMGMT> implicitly, using I<propquery> as property query string.
 As output from this function, I<*keymgmt> will be assigned the B<EVP_KEYMGMT>
 that was used, if the export was successful, otherwise it will be assigned NULL.
-I<domainparams> decides if I<pk> should be considered domain parameters or the
-actual key.
 
 =head1 RETURN VALUES
 
diff --git a/doc/man3/EVP_PKEY_check.pod b/doc/man3/EVP_PKEY_check.pod
index 95b57a3fb8..2398b61b64 100644
--- a/doc/man3/EVP_PKEY_check.pod
+++ b/doc/man3/EVP_PKEY_check.pod
@@ -18,7 +18,7 @@ EVP_PKEY_private_check, EVP_PKEY_pairwise_check
 
 =head1 DESCRIPTION
 
-EVP_PKEY_param_check() validates the domain parameters component of the key
+EVP_PKEY_param_check() validates the parameters component of the key
 given by B<ctx>.
 
 EVP_PKEY_public_check() validates the public component of the key given by B<ctx>.
diff --git a/doc/man3/EVP_PKEY_fromdata.pod b/doc/man3/EVP_PKEY_fromdata.pod
index 0e3dc5c29f..ed8c668e90 100644
--- a/doc/man3/EVP_PKEY_fromdata.pod
+++ b/doc/man3/EVP_PKEY_fromdata.pod
@@ -4,7 +4,7 @@
 
 EVP_PKEY_param_fromdata_init, EVP_PKEY_key_fromdata_init, EVP_PKEY_fromdata,
 EVP_PKEY_param_fromdata_settable, EVP_PKEY_key_fromdata_settable
-- functions to create domain parameters and keys from user data
+- functions to create key parameters and keys from user data
 
 =head1 SYNOPSIS
 
@@ -19,12 +19,12 @@ EVP_PKEY_param_fromdata_settable, EVP_PKEY_key_fromdata_settable
 =head1 DESCRIPTION
 
 EVP_PKEY_param_fromdata_init() initializes a public key algorithm context
-for creating domain parameters from user data.
+for creating key parameters from user data.
 
 EVP_PKEY_key_fromdata_init() initializes a public key algorithm context for
 creating a key from user data.
 
-EVP_PKEY_fromdata() creates domain parameters or a key, given data from
+EVP_PKEY_fromdata() creates key parameters or a key, given data from
 I<params> and a context that's been initialized with
 EVP_PKEY_param_fromdata_init() or EVP_PKEY_key_fromdata_init().  The result is
 written to I<*ppkey>.
diff --git a/doc/man3/OSSL_SERIALIZER_CTX_new_by_EVP_PKEY.pod b/doc/man3/OSSL_SERIALIZER_CTX_new_by_EVP_PKEY.pod
index caa9294bcc..8cc7cfbf30 100644
--- a/doc/man3/OSSL_SERIALIZER_CTX_new_by_EVP_PKEY.pod
+++ b/doc/man3/OSSL_SERIALIZER_CTX_new_by_EVP_PKEY.pod
@@ -36,11 +36,11 @@ OSSL_SERIALIZER_Parameters_TO_TEXT_PQ
 
  #define OSSL_SERIALIZER_PUBKEY_TO_PEM_PQ "format=pem,type=public"
  #define OSSL_SERIALIZER_PrivateKey_TO_PEM_PQ "format=pem,type=private"
- #define OSSL_SERIALIZER_Parameters_TO_PEM_PQ "format=pem,type=domainparams"
+ #define OSSL_SERIALIZER_Parameters_TO_PEM_PQ "format=pem,type=parameters"
 
  #define OSSL_SERIALIZER_PUBKEY_TO_TEXT_PQ "format=text,type=public"
  #define OSSL_SERIALIZER_PrivateKey_TO_TEXT_PQ "format=text,type=private"
- #define OSSL_SERIALIZER_Parameters_TO_TEXT_PQ "format=text,type=domainparams"
+ #define OSSL_SERIALIZER_Parameters_TO_TEXT_PQ "format=text,type=parameters"
 
 =head1 DESCRIPTION
 
diff --git a/doc/man3/d2i_PrivateKey.pod b/doc/man3/d2i_PrivateKey.pod
index dc3618eb53..4b7a326c0d 100644
--- a/doc/man3/d2i_PrivateKey.pod
+++ b/doc/man3/d2i_PrivateKey.pod
@@ -36,7 +36,7 @@ use any key specific format or PKCS#8 unencrypted PrivateKeyInfo format. The
 B<type> parameter should be a public key algorithm constant such as
 B<EVP_PKEY_RSA>. An error occurs if the decoded key does not match B<type>.
 d2i_PublicKey() does the same for public keys.
-d2i_KeyParams() does the same for domain parameter keys.
+d2i_KeyParams() does the same for key parameters.
 
 d2i_AutoPrivateKey() is similar to d2i_PrivateKey() except it attempts to
 automatically detect the private key format.
@@ -44,7 +44,7 @@ automatically detect the private key format.
 i2d_PrivateKey() encodes B<key>. It uses a key specific format or, if none is
 defined for that key type, PKCS#8 unencrypted PrivateKeyInfo format.
 i2d_PublicKey() does the same for public keys.
-i2d_KeyParams() does the same for domain parameter keys.
+i2d_KeyParams() does the same for key parameters.
 These functions are similar to the d2i_X509() functions; see L<d2i_X509(3)>.
 
 =head1 NOTES
diff --git a/doc/man7/provider-keymgmt.pod b/doc/man7/provider-keymgmt.pod
index 94427de89f..e9e4de5622 100644
--- a/doc/man7/provider-keymgmt.pod
+++ b/doc/man7/provider-keymgmt.pod
@@ -14,47 +14,29 @@ provider-keymgmt - The KEYMGMT library E<lt>-E<gt> provider functions
   * pointers in OSSL_DISPATCH arrays.
   */
 
- /* Key domain parameter creation and destruction */
- void *OP_keymgmt_importdomparams(void *provctx, const OSSL_PARAM params[]);
- void *OP_keymgmt_gendomparams(void *provctx, const OSSL_PARAM params[]);
- void OP_keymgmt_freedomparams(void *domparams);
+ /* Key object (keydata) creation and destruction */
+ void *OP_keymgmt_new(void *provctx);
+ void OP_keymgmt_free(void *keydata);
 
- /* Key domain parameter export */
- int OP_keymgmt_exportdomparams(void *domparams, OSSL_PARAM params[]);
+ /* Key object information */
+ int OP_keymgmt_get_params(void *keydata, OSSL_PARAM params[]);
+ const OSSL_PARAM *OP_keymgmt_gettable_params(void);
 
- /* Key domain parameter discovery */
- const OSSL_PARAM *OP_keymgmt_importdomparam_types(void);
- const OSSL_PARAM *OP_keymgmt_exportdomparam_types(void);
+ /* Key object content checks */
+ int OP_keymgmt_has(void *keydata, int selection);
 
- /* Key domain parameter information */
- int OP_keymgmt_get_domparam_params(void *domparams, OSSL_PARAM params[]);
- const OSSL_PARAM *OP_keymgmt_gettable_domparam_params(void);
-
- /* Key domain parameter validation */
- int OP_keymgmt_validate_domparams(void *key);
-
- /* Key creation and destruction */
- void *OP_keymgmt_importkey(void *provctx, const OSSL_PARAM params[]);
- void *OP_keymgmt_genkey(void *provctx,
-                         void *domparams, const OSSL_PARAM genkeyparams[]);
- void *OP_keymgmt_loadkey(void *provctx, void *id, size_t idlen);
- void OP_keymgmt_freekey(void *key);
-
- /* Key export */
- int OP_keymgmt_exportkey(void *key, OSSL_PARAM params[]);
-
- /* Key discovery */
- const OSSL_PARAM *OP_keymgmt_importkey_types(void);
- const OSSL_PARAM *OP_keymgmt_exportkey_types(void);
+ /* Discovery of supported operations */
+ const char *OP_keymgmt_query_operation_name(int operation_id);
 
- /* Key information */
- int OP_keymgmt_get_key_params(void *key, OSSL_PARAM params[]);
- const OSSL_PARAM *OP_keymgmt_gettable_key_params(void);
+ /* Key object import and export functions */
+ int OP_keymgmt_import(int selection, void *keydata, const OSSL_PARAM params[]);
+ const OSSL_PARAM *OP_keymgmt_import_types, (int selection);
+ int OP_keymgmt_export(int selection, void *keydata,
+                       OSSL_CALLBACK *param_cb, void *cbarg);
+ const OSSL_PARAM *OP_keymgmt_export_types(int selection);
 
- /* Key validation */
- int OP_keymgmt_validate_public(void *key);
- int OP_keymgmt_validate_private(void *key);
- int OP_keymgmt_validate_pairwise(void *key);
+ /* Key object validation */
+ int OP_keymgmt_validate(void *keydata, int selection);
 
  /* Discovery of supported operations */
  const char *OP_keymgmt_query_operation_name(int operation_id);
@@ -70,8 +52,7 @@ works with in tandem, they must belong to the same provider.
 The OpenSSL libraries will ensure that they do.
 
 The primary responsibility of the KEYMGMT operation is to hold the
-provider side domain parameters and keys for the OpenSSL library
-EVP_PKEY structure.
+provider side key data for the OpenSSL library EVP_PKEY structure.
 
 All "functions" mentioned here are passed as function pointers between
 F<libcrypto> and the provider in B<OSSL_DISPATCH> arrays via
@@ -83,133 +64,147 @@ All these "functions" have a corresponding function type definition
 named B<OSSL_{name}_fn>, and a helper function to retrieve the
 function pointer from a B<OSSL_DISPATCH> element named
 B<OSSL_get_{name}>.
-For example, the "function" OP_keymgmt_importdomparams() has these:
+For example, the "function" OP_keymgmt_new() has these:
 
- typedef void *
-     (OSSL_OP_keymgmt_importdomparams_fn)(void *provctx,
-                                          const OSSL_PARAM params[]);
- static ossl_inline OSSL_OP_keymgmt_importdomparams_fn
-     OSSL_get_OP_keymgmt_importdomparams(const OSSL_DISPATCH *opf);
+ typedef void *(OSSL_OP_keymgmt_new_fn)(void *provctx);
+ static ossl_inline OSSL_OP_keymgmt_new_fn
+     OSSL_get_OP_keymgmt_new(const OSSL_DISPATCH *opf);
 
 B<OSSL_DISPATCH> arrays are indexed by numbers that are provided as
 macros in L<openssl-core_numbers.h(7)>, as follows:
 
- OP_keymgmt_importdomparams      OSSL_FUNC_KEYMGMT_IMPORTDOMPARAMS
- OP_keymgmt_gendomparams         OSSL_FUNC_KEYMGMT_GENDOMPARAMS
- OP_keymgmt_freedomparams        OSSL_FUNC_KEYMGMT_FREEDOMPARAMS
- OP_keymgmt_exportdomparams      OSSL_FUNC_KEYMGMT_EXPORTDOMPARAMS
- OP_keymgmt_importdomparam_types OSSL_FUNC_KEYMGMT_IMPORTDOMPARAM_TYPES
- OP_keymgmt_exportdomparam_types OSSL_FUNC_KEYMGMT_EXPORTDOMPARAM_TYPES
- OP_keymgmt_get_domparam_params  OSSL_FUNC_KEYMGMT_GET_DOMPARAM_PARAMS
- OP_keymgmt_gettable_domparam_params
-                                 OSSL_FUNC_KEYMGMT_GETTABLE_DOMPARAM_PARAMS
-
- OP_keymgmt_importkey            OSSL_FUNC_KEYMGMT_IMPORTKEY
- OP_keymgmt_genkey               OSSL_FUNC_KEYMGMT_GENKEY
- OP_keymgmt_loadkey              OSSL_FUNC_KEYMGMT_LOADKEY
- OP_keymgmt_freekey              OSSL_FUNC_KEYMGMT_FREEKEY
- OP_keymgmt_exportkey            OSSL_FUNC_KEYMGMT_EXPORTKEY
- OP_keymgmt_importkey_types      OSSL_FUNC_KEYMGMT_IMPORTKEY_TYPES
- OP_keymgmt_exportkey_types      OSSL_FUNC_KEYMGMT_EXPORTKEY_TYPES
- OP_keymgmt_get_key_params       OSSL_FUNC_KEYMGMT_GET_KEY_PARAMS
- OP_keymgmt_gettable_key_params  OSSL_FUNC_KEYMGMT_GETTABLE_KEY_PARAMS
+ OP_keymgmt_new                  OSSL_FUNC_KEYMGMT_NEW
+ OP_keymgmt_free                 OSSL_FUNC_KEYMGMT_FREE
+
+ OP_keymgmt_get_params           OSSL_FUNC_KEYMGMT_GET_PARAMS
+ OP_keymgmt_gettable_params      OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS
 
  OP_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME
 
- OP_keymgmt_validate_domparams   OSSL_FUNC_KEYMGMT_VALIDATE_DOMPARAMS
- OP_keymgmt_validate_public      OSSL_FUNC_KEYMGMT_VALIDATE_PUBLIC
- OP_keymgmt_validate_private     OSSL_FUNC_KEYMGMT_VALIDATE_PRIVATE
- OP_keymgmt_validate_pairwise    OSSL_FUNC_KEYMGMT_VALIDATE_PAIRWISE
+ OP_keymgmt_has                  OSSL_FUNC_KEYMGMT_HAS
+ OP_keymgmt_validate             OSSL_FUNC_KEYMGMT_VALIDATE
 
-=head2 Domain Parameter Functions
+ OP_keymgmt_import               OSSL_FUNC_KEYMGMT_IMPORT
+ OP_keymgmt_import_types         OSSL_FUNC_KEYMGMT_IMPORT_TYPES
+ OP_keymgmt_export               OSSL_FUNC_KEYMGMT_EXPORT
+ OP_keymgmt_export_types         OSSL_FUNC_KEYMGMT_EXPORT_TYPES
 
-OP_keymgmt_importdomparams() should create a provider side structure
-for domain parameters, with values taken from the passed B<OSSL_PARAM>
-array I<params>.
 
-OP_keymgmt_gendomparams() should generate domain parameters and create
-a provider side structure for them.
-Values of the passed B<OSSL_PARAM> array I<params> should be used as
-input for parameter generation.
+=head2 Key Objects
 
-OP_keymgmt_freedomparams() should free the passed provider side domain
-parameter structure I<domparams>.
+A key object is a collection of data for an asymmetric key, and is
+represented as I<keydata> in this manual.
 
-OP_keymgmt_exportdomparams() should extract values from the passed
-provider side domain parameter structure I<domparams> into the passed
-B<OSSL_PARAM> I<params>.
-Only the values specified in I<params> should be extracted.
+The exact contents of a key object are defined by the provider, and it
+is assumed that different operations in one and the same provider use
+the exact same structure to represent this collection of data, so that
+for example, a key object that has been created using the KEYMGMT
+interface that we document here can be passed as is to other provider
+operations, such as OP_signature_sign_init() (see
+L<provider-signature(7)>).
 
-OP_keymgmt_importdomparam_types() should return a constant array of
-descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importdomparams()
-can handle.
+With some of the KEYMGMT functions, it's possible to select a specific
+subset of data to handle, governed by the bits in a I<selection>
+indicator.  The bits are:
+
+=over 4
 
-OP_keymgmt_exportdomparam_types() should return a constant array of
-descriptor B<OSSL_PARAM>, for parameters that can be exported with
-OP_keymgmt_exportdomparams().
+=item B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY>
 
-OP_keymgmt_get_domparam_params() should extract information data
-associated with the given I<domparams>,
-see L</Information Parameters>.
+Indicating that the private key data in a key object should be
+considered.
 
-OP_keymgmt_gettable_domparam_params() should return a constant array
-of descriptor B<OSSL_PARAM>, for parameters that
-OP_keymgmt_get_domparam_params() can handle.
+=item B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>
 
-OP_keymgmt_validate_domparams() should return a value of 1 if the
-domain parameters are valid, or 0 for invalid.
+Indicating that the public key data in a key object should be
+considered.
 
-=head2 Key functions
+=item B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS>
 
-OP_keymgmt_importkey() should create a provider side structure
-for keys, with values taken from the passed B<OSSL_PARAM> array
-I<params>.
+Indicating that the domain parameters in a key object should be
+considered.
 
-OP_keymgmt_genkey() should generate keys and create a provider side
-structure for them.
-Values from the passed domain parameters I<domparams> as well as from
-the passed B<OSSL_PARAM> array I<params> should be used as input for
-key generation.
+=item B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>
 
-OP_keymgmt_loadkey() should return a provider side key structure with
-a key loaded from a location known only to the provider, identitified
-with the identity I<id> of size I<idlen>.
-This identity is internal to the provider and is retrieved from the
-provider through other means.
+Indicating that other parameters in a key object should be
+considered.
 
-=for comment Right now, OP_keymgmt_loadkey is useless, but will be
-useful as soon as we have a OSSL_STORE interface
+Other parameters are key parameters that don't fit any other
+classification.  In other words, this particular selector bit works as
+a last resort bit bucket selector.
 
-OP_keymgmt_freekey() should free the passed I<key>.
+=back
 
-OP_keymgmt_exportkey() should extract values from the passed
-provider side key I<key> into the passed B<OSSL_PARAM> I<params>.
-Only the values specified in I<params> should be extracted.
+Some selector bits have also been combined for easier use:
 
-OP_keymgmt_importkey_types() should return a constant array of
-descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_importkey()
-can handle.
+=over 4
+
+=item B<OSSL_KEYMGMT_SELECT_ALL_PARAMETERS>
+
+Indicating that all key object parameters should be considered,
+regardless of their more granular classification.
 
-OP_keymgmt_exportkey_types() should return a constant array of
-descriptor B<OSSL_PARAM>, for parameters that can be exported with
-OP_keymgmt_exportkeys().
+=for comment This should used by EVP functions such as
+EVP_PKEY_copy_parameters() and EVP_PKEY_cmp_parameters()
 
-OP_keymgmt_get_key_params() should extract information data associated
-with the given I<key>, see L</Information Parameters>.
+This is a combination of B<OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS> and
+B<OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS>.
 
-OP_keymgmt_gettable_key_params() should return a constant array of
-descriptor B<OSSL_PARAM>, for parameters that
-OP_keymgmt_get_key_params() can handle.
+=for comment If more parameter categories are added, they should be
+mentioned here too.
 
-OP_keymgmt_validate_public() should return 1 if the public component of the
-key is valid, or 0 if invalid.
-OP_keymgmt_validate_private() should return 1 if the private component of the
-key is valid, or 0 if invalid.
-OP_keymgmt_validate_pairwise() should return 1 if the the pairwise consistency
-of the key is valid, or 0 if invalid.
+=item B<OSSL_KEYMGMT_SELECT_KEYPAIR>
 
+Indicating that both the whole key pair in a key object should be
+considered, i.e. the combination of public and private key.
+
+This is a combination of B<OSSL_KEYMGMT_SELECT_PRIVATE_KEY> and
+B<OSSL_KEYMGMT_SELECT_PUBLIC_KEY>.
+
+=item B<OSSL_KEYMGMT_SELECT_ALL>
+
+Indicating that everything in a key object should be considered.
+
+=back
 
-=head2 Supported operations
+The exact interpretation of those bits or how they combine is left to
+each function where you can specify a selector.
+
+=for comment One might think that a combination of bits means that all
+the selected data subsets must be considered, but then you have to
+consider that when comparing key objects (future function), an
+implementation might opt to not compare the private key if it has
+compared the public key, since a match of one half implies a match of
+the other half.
+
+=head2 Constructing and Destructing Functions
+
+OP_keymgmt_new() should create a provider side key object.  The
+provider context I<provctx> is passed and may be incorporated in the
+key object, but that is not mandatory.
+
+OP_keymgmt_free() should free the passed I<keydata>.
+
+The constructor and destructor are mandatory, a KEYMGMT implementation
+without them will not be accepted.
+
+=for comment when new constructors appear, it's sufficient if only one
+of them is present.  The remark above will have to change to reflect
+that.
+
+=head2 Key Object Information Functions
+
+OP_keymgmt_get_params() should extract information data associated
+with the given I<keydata>, see L</Information Parameters>.
+
+OP_keymgmt_gettable_params() should return a constant array of
+descriptor B<OSSL_PARAM>, for parameters that OP_keymgmt_get_params()
+can handle.
+
+If OP_keymgmt_gettable_params() is present, OP_keymgmt_get_params()
+must also be present.
+
+=head2 Key Object Checking Functions