rsa/psa/pk: warn more against PKCS#1 v1.5 decrypt

Signed-off-by: Manuel Pégourié-Gonnard <[email protected]>

include/mbedtls/pk.h

@@ -930,6 +930,15 @@ int mbedtls_pk_sign_restartable(mbedtls_pk_context *ctx,
 /**
  * \brief           Decrypt message (including padding if relevant).
  *
+ * \warning         When using PKCS#1 v1.5 (see note below), this is an
+ *                  inherently dangerous function (CWE-242) and the return value
+ *                  is sensitive, see mbedtls_rsa_rsaes_pkcs1_v15_decrypt().
+ *
+ * \note            For keys of type #MBEDTLS_PK_RSA, the encryption algorithm is
+ *                  either PKCS#1 v1.5 or OAEP, depending on the padding mode in
+ *                  the underlying RSA context. For a pk object constructed by
+ *                  parsing, this is PKCS#1 v1.5 by default.
+ *
  * \param ctx       The PK context to use. It must have been set up
  *                  with a private key.
  * \param input     Input to decrypt
@@ -940,11 +949,6 @@ int mbedtls_pk_sign_restartable(mbedtls_pk_context *ctx,
  * \param f_rng     RNG function, must not be \c NULL.
  * \param p_rng     RNG parameter
  *
- * \note            For keys of type #MBEDTLS_PK_RSA, the signature algorithm is
- *                  either PKCS#1 v1.5 or OAEP, depending on the padding mode in
- *                  the underlying RSA context. For a pk object constructed by
- *                  parsing, this is PKCS#1 v1.5 by default.
- *
  * \return          0 on success, or a specific error code.
  */
 int mbedtls_pk_decrypt(mbedtls_pk_context *ctx,

include/mbedtls/rsa.h

@@ -696,7 +696,9 @@ int mbedtls_rsa_rsaes_oaep_encrypt(mbedtls_rsa_context *ctx,
  *
  * \warning        When \p ctx->padding is set to #MBEDTLS_RSA_PKCS_V15,
  *                 mbedtls_rsa_rsaes_pkcs1_v15_decrypt() is called, which is an
- *                 inherently dangerous function (CWE-242).
+ *                 inherently dangerous function (CWE-242). In that case, the
+ *                 return value of this function is sensitive, see the
+ *                 documentation of mbedtls_rsa_rsaes_pkcs1_v15_decrypt().
  *
  * \note           The output buffer length \c output_max_len should be
  *                 as large as the size \p ctx->len of \p ctx->N (for example,
@@ -738,6 +740,9 @@ int mbedtls_rsa_pkcs1_decrypt(mbedtls_rsa_context *ctx,
  *                 it is used in a side channel free and safe way (eg.
  *                 implementing the TLS protocol as per 7.4.7.1 of RFC 5246),
  *                 the calling code is vulnerable.
+ *                 Specifically, callers need to ensure an adversary cannot
+ *                 distinguish between success, MBEDTLS_ERR_RSA_INVALID_PADDING
+ *                 and MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE via side channels.
  *
  * \note           The output buffer length \c output_max_len should be
  *                 as large as the size \p ctx->len of \p ctx->N, for example,

include/psa/crypto.h

@@ -3125,6 +3125,12 @@ psa_status_t psa_asymmetric_encrypt(mbedtls_svc_key_id_t key,
 /**
  * \brief Decrypt a short message with a private key.
  *
+ * \warning         When \p alg is #PSA_ALG_RSA_PKCS1V15_CRYPT, this is an
+ *                  inherently dangerous function (CWE-242): unless it is used
+ *                  in a side channel free and safe way (eg. implementing the
+ *                  TLS protocol as per 7.4.7.1 of RFC 5246), the calling code
+ *                  is vulnerable.
+ *
  * \param key                   Identifier of the key to use for the operation.
  *                              It must be an asymmetric key pair. It must
  *                              allow the usage #PSA_KEY_USAGE_DECRYPT.