DOCS: Add internal docs for EVP_PKEY and the export functions

Functions covered:

- evp_pkey_export_to_provider()
- evp_pkey_upgrade_to_provider()

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/11148)

1 files changed, 56 insertions, 0 deletions

diff --git a/doc/internal/man7/EVP_PKEY.pod b/doc/internal/man7/EVP_PKEY.pod
new file mode 100644
index 0000000000..a37ca9eecc
--- /dev/null
+++ b/doc/internal/man7/EVP_PKEY.pod
@@ -0,0 +1,56 @@
+=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