From 5e32b3e3fae489e071a891ba27035b31816d7463 Mon Sep 17 00:00:00 2001 From: Dmitry Belyavskiy Date: Tue, 31 Mar 2026 16:15:48 +0200 Subject: [PATCH] Document semantic changes for EVP_get_*by* functions Reviewed-by: Eugene Syromiatnikov Reviewed-by: Tom Cosgrove (Merged from https://github.com/openssl/openssl/pull/30646) --- doc/man7/ossl-guide-migration.pod | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/doc/man7/ossl-guide-migration.pod b/doc/man7/ossl-guide-migration.pod index c4877fa9ace..3619c1fe57a 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 and B 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/B 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 (with B +or B) 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 -- 2.47.3