rsa: fix version of rsa implicit rejection introduction

[openssl.git] / doc / man3 / EVP_PKEY_CTX_ctrl.pod

diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod
index 7c8db14cb6c40169bcc58abbf21ea8642b64d3b5..edbcb0dce854b8c05161925a5c63ad4e723e6866 100644 (file)
--- a/doc/man3/EVP_PKEY_CTX_ctrl.pod
+++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod
@@ -116,7 +116,7 @@ EVP_PKEY_CTX_set_kem_op
  int EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
  int EVP_PKEY_CTX_get_rsa_oaep_md_name(EVP_PKEY_CTX *ctx, char *name,
                                        size_t namelen);
- int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char *label,
+ int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, void *label,
                                       int len);
  int EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char **label);
 
@@ -176,9 +176,9 @@ EVP_PKEY_CTX_set_kem_op
  int EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id);
  int EVP_PKEY_CTX_get1_id_len(EVP_PKEY_CTX *ctx, size_t *id_len);
 
-Deprecated since OpenSSL 3.0, can be hidden entirely by defining
-B<OPENSSL_API_COMPAT> with a suitable version value, see
-L<openssl_user_macros(7)>:
+The following functions have been deprecated since OpenSSL 3.0, and can be
+hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
+see L<openssl_user_macros(7)>:
 
  #include <openssl/rsa.h>
 
@@ -270,8 +270,8 @@ EVP_PKEY_CTX_get_rsa_padding() gets the RSA padding mode for I<ctx>.
 
 EVP_PKEY_CTX_set_rsa_pss_saltlen() sets the RSA PSS salt length to I<saltlen>.
 As its name implies it is only supported for PSS padding. If this function is
-not called then the maximum salt length is used when signing and auto detection
-when verifying. Three special values are supported:
+not called then the salt length is maximized up to the digest length when
+signing and auto detection when verifying. Four special values are supported:
 
 =over 4
 
@@ -289,6 +289,13 @@ causes the salt length to be automatically determined based on the
 B<PSS> block structure when verifying.  When signing, it has the same
 meaning as B<RSA_PSS_SALTLEN_MAX>.
 
+=item B<RSA_PSS_SALTLEN_AUTO_DIGEST_MAX>
+
+causes the salt length to be automatically determined based on the B<PSS> block
+structure when verifying, like B<RSA_PSS_SALTLEN_AUTO>.  When signing, the salt
+length is maximized up to a maximum of the digest length to comply with FIPS
+186-4 section 5.5.
+
 =back
 
 EVP_PKEY_CTX_get_rsa_pss_saltlen() gets the RSA PSS salt length for I<ctx>.
@@ -356,8 +363,8 @@ EVP_MD object instead. Note that only known, built-in EVP_MD objects will be
 returned. The EVP_MD object may be NULL if the digest is not one of these (such
 as a digest only implemented in a third party provider).
 
-EVP_PKEY_CTX_set0_rsa_oaep_label() sets the RSA OAEP label to
-I<label> and its length to I<len>. If I<label> is NULL or I<len> is 0,
+EVP_PKEY_CTX_set0_rsa_oaep_label() sets the RSA OAEP label to binary data
+I<label> and its length in bytes to I<len>. If I<label> is NULL or I<len> is 0,
 the label is cleared. The library takes ownership of the label so the
 caller should not free the original memory pointed to by I<label>.
 The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING>.
@@ -386,6 +393,15 @@ this behaviour should be tolerated then
 OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION should be set to the actual
 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
+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.
+
 =head2 DSA parameters
 
 EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used for DSA