Add note about use of EVP_PKEY in different libctxs

Co-authored-by: Shane Lontis <slontis@oracle.com>
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/26309)

diff --git a/doc/man3/EVP_PKEY_new.pod b/doc/man3/EVP_PKEY_new.pod
index 72d129deff2460bfa9e13fb18fd4cf84acbc2754..0a56600c2b60fd3ed0ff8914624b9833f40d481d 100644 (file)
--- a/doc/man3/EVP_PKEY_new.pod
+++ b/doc/man3/EVP_PKEY_new.pod
@@ -219,7 +219,19 @@ general private key without reference to any particular algorithm.
 The structure returned by EVP_PKEY_new() is empty. To add a private or public
 key to this empty structure use the appropriate functions described in
 L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA(3)>, L<EVP_PKEY_set1_DH(3)> or
-L<EVP_PKEY_set1_EC_KEY(3)>.
+L<EVP_PKEY_set1_EC_KEY(3)> for legacy key types implemented in internal
+OpenSSL providers.
+
+For fully provider-managed key types (see L<provider-keymgmt(7)>),
+possibly implemented in external providers, use functions such as
+L<EVP_PKEY_set1_encoded_public_key(3)> or L<EVP_PKEY_fromdata(3)>
+to populate key data.
+
+Generally caution is advised for using an B<EVP_PKEY> structure across
+different library contexts: In order for an B<EVP_PKEY> to be shared by
+multiple library contexts the providers associated with the library contexts
+must have key managers that support the key type and implement the
+OSSL_FUNC_keymgmt_import() and OSSL_FUNC_keymgmt_export() functions.
 
 =head1 RETURN VALUES