=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