Document semantic changes for EVP_get_*by* functions

Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org>
Reviewed-by: Tom Cosgrove <tom.cosgrove@arm.com>
(Merged from https://github.com/openssl/openssl/pull/30646)

diff --git a/doc/man7/ossl-guide-migration.pod b/doc/man7/ossl-guide-migration.pod
index c4877fa9ace9579f799cd721d32944fb4ef333bf..3619c1fe57ac04d65fe756d8510d010a0ca81d72 100644 (file)
--- a/doc/man7/ossl-guide-migration.pod
+++ b/doc/man7/ossl-guide-migration.pod
@@ -234,6 +234,27 @@ useful internally because the type is opaque and there exist no setter functions
 Hence, there never was a real use case for the function and calls to it can
 simply be removed.
 
+=head3 Practical behaviour change of EVP_get_cipherby* and EVP_get_digestby* functions
+
+Before 4.0 functions B<EVP_get_cipherby*> and B<EVP_get_digestby*> were often
+used as fallback for EVP_CIPHER_fetch() and EVP_MD_fetch() implying the
+possibility to access an algorithm implementation provided by an engine. In
+case when an engine-provided algorithm was not available, these functions on
+success return the implementation from the default OpenSSL library context with
+default properties. Version 4.0 doesn't support engines, so, on success, these
+functions always return the implementation from the default OpenSSL library
+context with default properties. This is probably not the desired result for
+applications that use a nondefault library context.
+
+The other difference between B<EVP_get_cipherby*>/B<EVP_get_digestby*> and
+EVP_CIPHER_fetch()/EVP_MD_fetch() is that the former functions deal with
+algorithm aliases algorithm aliases added via OBJ_NAME_add(), and the newer
+ones don't (except the ones declared in a specific provider as explicit
+aliases). Applications wishing to preserve alias handling behaviour can first
+check for an alias using B<OBJ_NAME_get()> (with B<OBJ_NAME_TYPE_CIPHER_METH>
+or B<OBJ_NAME_TYPE_MD_METH>) and fall back to EVP_CIPHER_fetch() or
+EVP_MD_fetch() if no match is found.
+
 =head1 OPENSSL 3.6
 
 =head2 Main Changes from OpenSSL 3.5