=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