Commit 5e32b3e3fa for openssl.org

commit 5e32b3e3fae489e071a891ba27035b31816d7463
Author: Dmitry Belyavskiy <beldmit@gmail.com>
Date:   Tue Mar 31 16:15:48 2026 +0200

    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 c4877fa9ac..3619c1fe57 100644
--- 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