Document the change in behaviour of the the low level key getters/setters

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14319)

2 files changed, 20 insertions, 14 deletions

diff --git a/doc/internal/man3/evp_pkey_export_to_provider.pod b/doc/internal/man3/evp_pkey_export_to_provider.pod
index 65fb7109e0..833ff44d53 100644
--- a/doc/internal/man3/evp_pkey_export_to_provider.pod
+++ b/doc/internal/man3/evp_pkey_export_to_provider.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-evp_pkey_export_to_provider, evp_pkey_copy_downgraded, evp_pkey_downgrade
+evp_pkey_export_to_provider, evp_pkey_copy_downgraded, evp_pkey_get_legacy
 - internal EVP_PKEY support functions for providers
 
 =head1 SYNOPSIS
@@ -14,7 +14,7 @@ evp_pkey_export_to_provider, evp_pkey_copy_downgraded, evp_pkey_downgrade
                                    EVP_KEYMGMT **keymgmt,
                                    const char *propquery);
  int evp_pkey_copy_downgraded(EVP_PKEY **dest, const EVP_PKEY *src);
- int evp_pkey_downgrade(EVP_PKEY *pk);
+ void *evp_pkey_get_legacy(EVP_PKEY *pk);
 
 =head1 DESCRIPTION
 
@@ -37,11 +37,14 @@ For example, L<PEM_write_bio_PrivateKey_traditional(3)> uses this to try its
 best to get "traditional" PEM output even if the input B<EVP_PKEY> has a
 provider-native internal key.
 
-evp_pkey_downgrade() converts an B<EVP_PKEY> with a provider side "origin" key
-to one with a legacy "origin", if there's a corresponding legacy implementation.
-This clears the operation cache, except for the provider side "origin" key.
-This function is used in spots where provider side keys aren't yet supported,
-in an attempt to keep operating with available implementations.
+evp_pkey_get_legacy() obtains and returns a legacy key structure. If the
+EVP_PKEY already contains a legacy key then it is simply returned. If it is a
+provider based key, then a new legacy key is constructed based on the provider
+key. The legacy key is cached inside the EVP_PKEY and its value returned from
+this function. Subsequent calls to evp_pkey_get_legacy() will return the cached
+key. Subsequent changes to the provider key are not reflected back in the
+legacy key. Similarly changes to the legacy key are not reflected back in the
+provider key.
 
 =head1 RETURN VALUES
 
@@ -49,7 +52,7 @@ evp_pkey_export_to_provider() returns the provider key data if there was any
 allocated.  It also either sets I<*keymgmt> to the B<EVP_KEYMGMT> associated
 with the returned key data, or NULL on error.
 
-evp_pkey_downgrade() returns 1 on success or 0 on error.
+evp_pkey_get_legacy() returns the legacy key or NULL on error.
 
 =head1 NOTES
 
diff --git a/doc/internal/man7/EVP_PKEY.pod b/doc/internal/man7/EVP_PKEY.pod
index 7088b6cc08..cc738b9c28 100644
--- a/doc/internal/man7/EVP_PKEY.pod
+++ b/doc/internal/man7/EVP_PKEY.pod
@@ -65,7 +65,10 @@ The B<EVP_PKEY> internal keys are mutable.
 
 This is especially visible with internal legacy keys, since they can
 be extracted with functions like L<EVP_PKEY_get0_RSA(3)> and then
-modified at will with functions like L<RSA_set0_key(3)>.
+modified at will with functions like L<RSA_set0_key(3)>. Note that if the
+internal key is a provider key then the return value from functions such as
+L<EVP_PKEY_get0_RSA(3)> is a cached copy of the key. Changes to the cached
+copy are not reflected back in the provider key.
 
 Internal provider native keys are also possible to be modified, if the
 associated L<EVP_KEYMGMT(3)> implementation allows it.  This is done
@@ -187,11 +190,11 @@ takes care of the needs of the diverse operation the application may want to
 perform.
 
 Similarly an B<EVP_PKEY> with a provider native origin, will I<never> be
-downgraded to be I<transformed> into an B<EVP_PKEY> with a legacy origin.
-Instead we may have a cached copy of the provider key in legacy form. Once the
-cached copy is created it is never updated. Changes made to the provider key
-are not reflected back in the cached legacy copy. Similarly changes made to the
-cached legacy copy are not reflected back in the provider key.
+I<transformed> into an B<EVP_PKEY> with a legacy origin. Instead we may have a
+cached copy of the provider key in legacy form. Once the cached copy is created
+it is never updated. Changes made to the provider key are not reflected back in
+the cached legacy copy. Similarly changes made to the cached legacy copy are not
+reflected back in the provider key.
 
 =head1 SEE ALSO