Be more explicit about RSAES-PKCS#1v1.5 error handling

And add a note how to perform side-channel free error stack handling.

Signed-off-by: Hubert Kario <hkario@redhat.com>

Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/24159)

4 files changed, 25 insertions, 8 deletions

diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod
index edbcb0dce8..21ae20adb0 100644
--- a/doc/man3/EVP_PKEY_CTX_ctrl.pod
+++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod
@@ -396,11 +396,12 @@ negotiated protocol version. Otherwise it should be left unset.
 Similarly to the B<RSA_PKCS1_WITH_TLS_PADDING> above, since OpenSSL version
 3.2.0, the use of B<RSA_PKCS1_PADDING> will return a randomly generated message
 instead of padding errors in case padding checks fail. Applications that
-want to remain secure while using earlier versions of OpenSSL, still need to
+want to remain secure while using earlier versions of OpenSSL, or a provider
+that doesn't implement the implicit rejection mechanism, still need to
 handle both the error code from the RSA decryption operation and the
 returned message in a side channel secure manner.
 This protection against Bleichenbacher attacks can be disabled by setting
-the OSSL_ASYM_CIPHER_PARAM_IMPLICIT_REJECTION (an unsigned integer) to 0.
+B<OSSL_ASYM_CIPHER_PARAM_IMPLICIT_REJECTION> (an unsigned integer) to 0.
 
 =head2 DSA parameters
 
diff --git a/doc/man3/EVP_PKEY_decrypt.pod b/doc/man3/EVP_PKEY_decrypt.pod
index 67e3f2da1e..1f5d06b5b8 100644
--- a/doc/man3/EVP_PKEY_decrypt.pod
+++ b/doc/man3/EVP_PKEY_decrypt.pod
@@ -56,12 +56,21 @@ algorithm.
 In OpenSSL versions before 3.2.0, when used in PKCS#1 v1.5 padding,
 both the return value from the EVP_PKEY_decrypt() and the B<outlen> provided
 information useful in mounting a Bleichenbacher attack against the
-used private key. They had to processed in a side-channel free way.
+used private key. They had to be processed in a side-channel free way.
 
 Since version 3.2.0, the EVP_PKEY_decrypt() method when used with PKCS#1
-v1.5 padding doesn't return an error in case it detects an error in padding,
+v1.5 padding as implemented in the B<default> provider implements
+the implicit rejection mechanism (see
+B<OSSL_PKEY_PARAM_IMPLICIT_REJECTION> in L<provider-asym_cipher(7)>).
+That means it doesn't return an error when it detects an error in padding,
 instead it returns a pseudo-randomly generated message, removing the need
 of side-channel secure code from applications using OpenSSL.
+If OpenSSL is configured to use a provider that doesn't implement implicit
+rejection, the code still needs to handle the returned values
+using side-channel free code.
+Side-channel free handling of the error stack can be peformed using
+either a pair of unconditional L<ERR_set_mark(3)> and L<ERR_pop_to_mark(3)>
+calls or by using the L<ERR_clear_error(3)> call.
 
 =head1 EXAMPLES
 
diff --git a/doc/man3/RSA_public_encrypt.pod b/doc/man3/RSA_public_encrypt.pod
index 2ae6c7f290..5e0139b711 100644
--- a/doc/man3/RSA_public_encrypt.pod
+++ b/doc/man3/RSA_public_encrypt.pod
@@ -94,10 +94,17 @@ design. Prefer RSA_PKCS1_OAEP_PADDING.
 
 In OpenSSL before version 3.2.0, both the return value and the length of
 returned value could be used to mount the Bleichenbacher attack.
-Since version 3.2.0, OpenSSL does not return an error in case of padding
-checks failed. Instead it generates a random message based on used private
+Since version 3.2.0, the default provider in OpenSSL does not return an
+error when padding checks fail. Instead it generates a random
+message based on used private
 key and provided ciphertext so that application code doesn't have to implement
 a side-channel secure error handling.
+Applications that want to be secure against side-channel attacks with
+providers that don't implement implicit rejection, still need to
+handle the returned values using side-channel free code.
+Side-channel free handling of the error stack can be peformed using
+either a pair of unconditional L<ERR_set_mark(3)> and L<ERR_pop_to_mark(3)>
+calls or by using the L<ERR_clear_error(3)> call.
 
 =head1 CONFORMING TO
 
@@ -106,7 +113,7 @@ SSL, PKCS #1 v2.0
 =head1 SEE ALSO
 
 L<ERR_get_error(3)>, L<RAND_bytes(3)>,
-L<RSA_size(3)>
+L<RSA_size(3)>, L<EVP_PKEY_decrypt(3)>, L<EVP_PKEY_encrypt(3)>
 
 =head1 HISTORY
 
diff --git a/doc/man7/provider-asym_cipher.pod b/doc/man7/provider-asym_cipher.pod
index e3f11d8543..24fe160bf7 100644
--- a/doc/man7/provider-asym_cipher.pod
+++ b/doc/man7/provider-asym_cipher.pod
@@ -241,7 +241,7 @@ decryption. When set (non zero value), the decryption API will return
 a deterministically random value if the PKCS#1 v1.5 padding check fails.
 This makes exploitation of the Bleichenbacher significantly harder, even
 if the code using the RSA decryption API is not implemented in side-channel
-free manner. Set by default.
+free manner. Set by default. Requires provider support.
 
 =back