=pod

=head1 NAME

EVP_PKEY - an internal description

=head1 SYNOPSIS

 #include "crypto/evp.h"

 struct evp_pkey_st;

=head1 DESCRIPTION

I<This is not a complete description yet>

B<EVP_PKEY> is a complex type that's essentially a container for
private/public key key pairs, but has had other uses as well.

=for comment "uses" could as well be "abuses"...

It can contain the legacy form of keys -- i.e. pointers to the low
level key types, such as B<RSA>, B<DSA> and B<EC> --, but also the
provided form of keys -- i.e. pointers to provider side key data.
Those two forms are mutually exclusive; an B<EVP_PKEY> instance can't
contain both a key in legacy form and in provided form.  Regardless of
form, this key is commonly refered to as the "origin".

An B<EVP_PKEY> also contains a cache of provider side copies of the
key, each adapted for the provider that is going to use that copy to
perform some operation.
For a legacy "origin", the B<EVP_PKEY_ASN1_METHOD>'s functions
export_to() and dirty_cnt() must be implemented for such caching to be
possible.  For a provider side "origin", the B<EVP_KEYMGMT>'s function
OP_keymgmt_export() must be implemented.  In all cases, the receiving
B<EVP_KEYMGMT> must have an implemented OP_keygmt_import().

If such caching isn't supported, the operations that can be performed
with that key are limited to the same backend as the "origin" key
(ENGINE for legacy "origin" keys, provider for provider side "origin"
keys).

=head1 SEE ALSO

L<provider-keymgmt(7)>

=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
