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)

3 files changed, 131 insertions, 63 deletions

diff --git a/doc/internal/man3/evp_pkey_export_to_provider.pod b/doc/internal/man3/evp_pkey_export_to_provider.pod
new file mode 100644
index 0000000000..31e8ad02e4
--- /dev/null
+++ b/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
diff --git a/doc/internal/man3/evp_pkey_make_provided.pod b/doc/internal/man3/evp_pkey_make_provided.pod
deleted file mode 100644
index 3eb17e707b..0000000000
--- a/doc/internal/man3/evp_pkey_make_provided.pod
+++ /dev/null
@@ -1,63 +0,0 @@
-=pod
-
-=head1 NAME
-
-evp_pkey_make_provided - internal EVP_PKEY support functions for providers
-
-=head1 SYNOPSIS
-
- /* Only for EVP source */
- #include "evp_local.h"
-
- void *evp_pkey_make_provided(EVP_PKEY *pk, OPENSSL_CTX *libctx,
-                              EVP_KEYMGMT **keymgmt, const char *propquery);
-
-=head1 DESCRIPTION
-
-evp_pkey_make_provided() ensures that the B<EVP_PKEY> I<pk> is provided within
-the library context I<libctx> (NULL means the default context).  I<keymgmt>
-may point at a reference to a B<EVP_KEYMGMT>, and works as an input/output
-parameter.
-As input to this function, it can be used to specify a B<EVP_KEYMGMT> to be
-used for exporting.  If not (I<*keymgmt> is NULL), then this function will
-fetch an B<EVP_KEYMGMT> implicitly, using I<propquery> as property query string.
-As output from this function, I<*keymgmt> will be assigned the B<EVP_KEYMGMT>
-that was used, if the export was successful, otherwise it will be assigned NULL.
-
-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, by comparing the
-result of the legacy key's dirty_cnt() method with a copy of that
-result from last time evp_pkey_make_provided() was run with this
-B<EVP_PKEY>.
-If it has, the cache of already exported keys is cleared, and a new
-export is made with the new legacy key material.
-
-=head1 RETURN VALUES
-
-evp_pkey_make_provided() returns the provider key data that was exported if
-I<pk> was successfully provided.  Otherwise, NULL is returned.
-
-=head1 NOTES
-
-Some functions calling evp_pkey_make_provided() 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
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