Update the EVP_PKEY_get_id documentation

The documentation didn't mention the development where EVP_PKEY_get_id()
returns a negative value for provider-only implementations, and the
migration guide didn't mention how to cope with that.

Fixes #20497

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20501)

1 files changed, 22 insertions, 0 deletions

diff --git a/doc/man7/migration_guide.pod b/doc/man7/migration_guide.pod
index bad1eab873..5294f57225 100644
--- a/doc/man7/migration_guide.pod
+++ b/doc/man7/migration_guide.pod
@@ -2242,6 +2242,28 @@ Use L<X509_load_http(3)> and L<X509_CRL_load_http(3)> instead.
 
 =back
 
+=head3 NID handling for provided keys and algorithms
+
+The following functions for NID (numeric id) handling have changed semantics.
+
+=over 4
+
+=item *
+
+EVP_PKEY_id(), EVP_PKEY_get_id()
+
+This function was previously used to reliably return the NID of
+an EVP_PKEY object, e.g., to look up the name of the algorithm of
+such EVP_PKEY by calling L<OBJ_nid2sn(3)>. With the introduction
+of L<provider(7)>s EVP_PKEY_id() or its new equivalent
+L<EVP_PKEY_get_id(3)> might now also return the value -1
+(B<EVP_PKEY_KEYMGMT>) indicating the use of a provider to
+implement the EVP_PKEY object. Therefore, the use of
+L<EVP_PKEY_get0_type_name(3)> is recommended for retrieving
+the name of the EVP_PKEY algorithm.
+
+=back
+
 =head2 Using the FIPS Module in applications
 
 See L<fips_module(7)> and L<OSSL_PROVIDER-FIPS(7)> for details.