Add EVP_PKEY_todata() and EVP_PKEY_export() functions.

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14800)

5 files changed, 77 insertions, 3 deletions

diff --git a/doc/build.info b/doc/build.info
index 899a142f52..d9c5d8d4fc 100644
--- a/doc/build.info
+++ b/doc/build.info
@@ -1266,6 +1266,10 @@ DEPEND[html/man3/EVP_PKEY_supports_digest_nid.html]=man3/EVP_PKEY_supports_diges
 GENERATE[html/man3/EVP_PKEY_supports_digest_nid.html]=man3/EVP_PKEY_supports_digest_nid.pod
 DEPEND[man/man3/EVP_PKEY_supports_digest_nid.3]=man3/EVP_PKEY_supports_digest_nid.pod
 GENERATE[man/man3/EVP_PKEY_supports_digest_nid.3]=man3/EVP_PKEY_supports_digest_nid.pod
+DEPEND[html/man3/EVP_PKEY_todata.html]=man3/EVP_PKEY_todata.pod
+GENERATE[html/man3/EVP_PKEY_todata.html]=man3/EVP_PKEY_todata.pod
+DEPEND[man/man3/EVP_PKEY_todata.3]=man3/EVP_PKEY_todata.pod
+GENERATE[man/man3/EVP_PKEY_todata.3]=man3/EVP_PKEY_todata.pod
 DEPEND[html/man3/EVP_PKEY_verify.html]=man3/EVP_PKEY_verify.pod
 GENERATE[html/man3/EVP_PKEY_verify.html]=man3/EVP_PKEY_verify.pod
 DEPEND[man/man3/EVP_PKEY_verify.3]=man3/EVP_PKEY_verify.pod
@@ -2962,6 +2966,7 @@ html/man3/EVP_PKEY_settable_params.html \
 html/man3/EVP_PKEY_sign.html \
 html/man3/EVP_PKEY_size.html \
 html/man3/EVP_PKEY_supports_digest_nid.html \
+html/man3/EVP_PKEY_todata.html \
 html/man3/EVP_PKEY_verify.html \
 html/man3/EVP_PKEY_verify_recover.html \
 html/man3/EVP_RAND.html \
@@ -3536,6 +3541,7 @@ man/man3/EVP_PKEY_settable_params.3 \
 man/man3/EVP_PKEY_sign.3 \
 man/man3/EVP_PKEY_size.3 \
 man/man3/EVP_PKEY_supports_digest_nid.3 \
+man/man3/EVP_PKEY_todata.3 \
 man/man3/EVP_PKEY_verify.3 \
 man/man3/EVP_PKEY_verify_recover.3 \
 man/man3/EVP_RAND.3 \
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 4a6e9b31f5..1fee9f6ff9 100644
--- a/doc/internal/man3/evp_keymgmt_util_export_to_provider.pod
+++ b/doc/internal/man3/evp_keymgmt_util_export_to_provider.pod
@@ -33,7 +33,8 @@ OP_CACHE_ELEM
 =head1 DESCRIPTION
 
 evp_keymgmt_util_export() calls L<evp_keymgmt_export(3)> with the
-I<keymgmt> and I<keydata> from I<pk>.  This is a convenience function.
+I<keymgmt> and I<keydata> from I<pk>.  This is used as a
+helper for L<EVP_PKEY_todata(3)>.
 
 evp_keymgmt_util_export_to_provider() exports cached key material
 (provider side key material) from the given key I<pk> to a provider
diff --git a/doc/man3/EVP_PKEY_fromdata.pod b/doc/man3/EVP_PKEY_fromdata.pod
index 1c85474662..d24fb34a25 100644
--- a/doc/man3/EVP_PKEY_fromdata.pod
+++ b/doc/man3/EVP_PKEY_fromdata.pod
@@ -78,6 +78,7 @@ public key and key parameters.
 =head1 NOTES
 
 These functions only work with key management methods coming from a provider.
+This is the mirror function to L<EVP_PKEY_todata(3)>.
 
 =for comment We may choose to make this available for legacy methods too... 
 
@@ -259,7 +260,7 @@ example with L<OSSL_PARAM_allocate_from_text(3)>.
 =head1 SEE ALSO
 
 L<EVP_PKEY_CTX_new(3)>, L<provider(7)>, L<EVP_PKEY_gettable_params(3)>,
-L<OSSL_PARAM(3)>,
+L<OSSL_PARAM(3)>, L<EVP_PKEY_todata(3)>,
 L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>,
 L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>,
 L<EVP_PKEY-ED25519(7)>
diff --git a/doc/man3/EVP_PKEY_todata.pod b/doc/man3/EVP_PKEY_todata.pod
new file mode 100644
index 0000000000..98ae484755
--- /dev/null
+++ b/doc/man3/EVP_PKEY_todata.pod
@@ -0,0 +1,64 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY_todata, EVP_PKEY_export
+- functions to return keys as an array of key parameters
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ int EVP_PKEY_todata(const EVP_PKEY *pkey, int selection, OSSL_PARAM **params);
+ int EVP_PKEY_export(const EVP_PKEY *pkey, int selection,
+                     OSSL_CALLBACK *export_cb, void *export_cbarg);
+
+=head1 DESCRIPTION
+
+The functions described here are used to extract B<EVP_PKEY> key values as an
+array of B<OSSL_PARAM>.
+
+EVP_PKEY_todata() extracts values from a key I<pkey> using the I<selection>.
+I<selection> is described in L<EVP_PKEY_fromdata(3)/Selections>.
+L<OSSL_PARAM_free(3)> should be used to free the returned parameters in
+I<*params>.
+
+EVP_PKEY_export() is similiar to EVP_PKEY_todata() but uses a callback
+I<export_cb> that gets passed the value of I<export_cbarg>.
+See L<openssl-core.h(7)> for more information about the callback. Note that the
+B<OSSL_PARAM> array that is passed to the callback is not persistent after the
+callback returns. The user must preserve the items of interest, or use
+EVP_PKEY_todata() if persistence is required.
+
+=head1 NOTES
+
+These functions only work with key management methods coming from a provider.
+This is the mirror function to L<EVP_PKEY_fromdata(3)>.
+
+=head1 RETURN VALUES
+
+EVP_PKEY_todata() and EVP_PKEY_export() return 1 for success and 0 for failure.
+
+=head1 SEE ALSO
+
+L<OSSL_PARAM(3)>, L<openssl-core.h(7)>,
+L<EVP_PKEY_fromdata(3)>,
+L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>,
+L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>,
+L<EVP_PKEY-ED25519(7)>
+
+=head1 HISTORY
+
+These functions were added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 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/man7/evp.pod b/doc/man7/evp.pod
index 74fc975ce1..307008f7ba 100644
--- a/doc/man7/evp.pod
+++ b/doc/man7/evp.pod
@@ -32,7 +32,8 @@ with a private key of a particular algorithm by using the functions
 described on the L<EVP_PKEY_fromdata(3)> page, or
 new keys can be generated using L<EVP_PKEY_keygen(3)>.
 EVP_PKEYs can be compared using L<EVP_PKEY_cmp(3)>, or printed using
-L<EVP_PKEY_print_private(3)>.
+L<EVP_PKEY_print_private(3)>. L<EVP_PKEY_todata(3)> can be used to convert a
+key back into an L<OSSL_PARAM(3)> array.
 
 The EVP_PKEY functions support the full range of asymmetric algorithm operations:
 
@@ -91,6 +92,7 @@ L<EVP_VerifyInit(3)>,
 L<EVP_EncodeInit(3)>,
 L<EVP_PKEY_new(3)>,
 L<EVP_PKEY_fromdata(3)>,
+L<EVP_PKEY_todata(3)>,
 L<EVP_PKEY_keygen(3)>,
 L<EVP_PKEY_print_private(3)>,
 L<EVP_PKEY_decrypt(3)>,