From: Tomas Mraz <tomas@openssl.org>
Date: Wed, 27 Dec 2023 18:21:49 +0000 (+0100)
Subject: Document the implications of setting engine-based low-level methods
X-Git-Tag: openssl-3.1.6~112
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f8462a352dfaa2cdce933dd2be48bf39ae91b381;p=thirdparty%2Fopenssl.git

Document the implications of setting engine-based low-level methods

Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/23063)

(cherry picked from commit dbb478a51d3f695ec713e9829a2353a0d2d61a59)
---

diff --git a/doc/man7/migration_guide.pod b/doc/man7/migration_guide.pod
index d9e4b37b2bf..28983ea600e 100644
--- a/doc/man7/migration_guide.pod
+++ b/doc/man7/migration_guide.pod
@@ -156,6 +156,14 @@ To ensure the future compatibility, the engines should be turned to providers.
 To prefer the provider-based hardware offload, you can specify the default
 properties to prefer your provider.
 
+Setting engine-based or application-based default low-level crypto method such
+as B<RSA_METHOD> or B<EC_KEY_METHOD> is still possible and keys inside the
+default provider will use the engine-based implementation for the crypto
+operations. However B<EVP_PKEY>s created by decoding by using B<OSSL_DECODER>,
+B<PEM_> or B<d2i_> APIs will be provider-based. To create a fully legacy
+B<EVP_PKEY>s L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_EC_KEY(3)> or similar
+functions must be used.
+
 =head3 Versioning Scheme
 
 The OpenSSL versioning scheme has changed with the OpenSSL 3.0 release. The new