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)
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
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
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
=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
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