Latest update.

doc/internal/man3/evp_pkey_export_to_provider.pod

@@ -0,0 +1,75 @@
+=pod
+
+=head1 NAME
+
+evp_pkey_export_to_provider, evp_pkey_upgrade_to_provider
+- internal EVP_PKEY support functions for providers
+
+=head1 SYNOPSIS
+
+ /* Only for EVP source */
+ #include "evp_local.h"
+
+ void *evp_pkey_export_to_provider(EVP_PKEY *pk, OPENSSL_CTX *libctx,
+                                   EVP_KEYMGMT **keymgmt,
+                                   const char *propquery);
+ void *evp_pkey_upgrade_to_provider(EVP_PKEY *pk, OPENSSL_CTX *libctx,
+                                    EVP_KEYMGMT **keymgmt,
+                                    const char *propquery);
+
+=head1 DESCRIPTION
+
+This manual uses the term "origin", which is explained in internal
+L<EVP_PKEY(7)>.
+
+evp_pkey_export_to_provider() exports the "origin" key contained in I<pk>
+to its operation cache to make it suitable for an B<EVP_KEYMGMT> given either
+with I<*keymgmt> or with an implicit fetch using I<libctx> (NULL means the
+default context), the name of the legacy type of I<pk>, and the I<propquery>
+(NULL means the default property query settings).
+
+If I<keymgmt> isn't NULL but I<*keymgmt> is, and the "origin" was successfully
+exported, then I<*keymgmt> is assigned the implicitly fetched B<EVP_KEYMGMT>.
+
+evp_pkey_upgrade_to_provider() exports the legacy "origin" key contained in
+I<pk> to it's provider side counterpart, then clears the legacy "origin" key
+along with other legacy data, and resets all the caches.  Otherwise, it works
+like evp_pkey_export_to_provider().
+
+I<evp_pkey_upgrade_to_provider() must be used with great care, only if there's
+no other way.>
+Most of the time, it's sufficient to use evp_pkey_export_to_provider(), but in
+case the key needs modification with data coming from a provided key, the key
+will need an upgrade.
+
+=head1 RETURN VALUES
+
+evp_pkey_export_to_provider() and evp_pkey_upgrade_to_provider() both return
+the provider key data that was exported if the "origin" was successfully
+exported to its target.  Otherwise, NULL is returned.
+
+=head1 NOTES
+
+Some functions calling evp_pkey_export_to_provider() or
+evp_pkey_upgrade_to_provider() may have received a const key, and may
+therefore have to cast the key to non-const form to call this function.  Since
+B<EVP_PKEY> is always dynamically allocated, this is OK.
+
+=head1 SEE ALSO
+
+L<OPENSSL_CTX(3)>, L<EVP_KEYMGMT(3)>
+
+=head1 HISTORY
+
+The functions described here were all added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2020 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