diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h index 68b0f4befa..e065e4166d 100644 --- a/include/mbedtls/pk.h +++ b/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, diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h index 3f0881a434..d528b0a864 100644 --- a/include/mbedtls/rsa.h +++ b/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, diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 2fe9f35ec3..1a86af7261 100644 --- a/include/psa/crypto.h +++ b/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.