From 3cdc7119726013ed9d7b27b251da83808201cae3 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Thu, 5 Oct 2017 10:09:31 +0100 Subject: [PATCH] Deprecate usage of RSA primitives with wrong key type Further, state explicitly that wrong key types need not be supported by alternative RSA implementations, and that those may instead return the newly introduced error code MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. --- include/mbedtls/rsa.h | 117 ++++++++++++++++++++++++++++++++++++++++-- library/error.c | 2 + 2 files changed, 115 insertions(+), 4 deletions(-) diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h index 7d7469d50..2ffb7ab3f 100644 --- a/include/mbedtls/rsa.h +++ b/include/mbedtls/rsa.h @@ -48,6 +48,7 @@ #define MBEDTLS_ERR_RSA_VERIFY_FAILED -0x4380 /**< The PKCS#1 verification failed. */ #define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE -0x4400 /**< The output buffer for decryption is not large enough. */ #define MBEDTLS_ERR_RSA_RNG_FAILED -0x4480 /**< The random generator failed to generate non-zeros. */ +#define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION -0x4500 /**< The implementation doesn't provide the requested operation. */ /* * RSA constants @@ -250,6 +251,15 @@ int mbedtls_rsa_private( mbedtls_rsa_context *ctx, * \param input buffer holding the data to be encrypted * \param output buffer that will hold the ciphertext * + * \deprecated It is deprecated and discouraged to call this function + * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary + * are likely to remove the mode argument and have it implicitly + * set to MBEDTLS_RSA_PUBLIC. + * + * \note Alternative implementations of RSA need not support + * mode being set to MBEDTLS_RSA_PRIVATE and may instead + * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code * * \note The output buffer must be as large as the size @@ -273,6 +283,15 @@ int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx, * \param input buffer holding the data to be encrypted * \param output buffer that will hold the ciphertext * + * \deprecated It is deprecated and discouraged to call this function + * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary + * are likely to remove the mode argument and have it implicitly + * set to MBEDTLS_RSA_PUBLIC. + * + * \note Alternative implementations of RSA need not support + * mode being set to MBEDTLS_RSA_PRIVATE and may instead + * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code * * \note The output buffer must be as large as the size @@ -299,6 +318,15 @@ int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx, * \param input buffer holding the data to be encrypted * \param output buffer that will hold the ciphertext * + * \deprecated It is deprecated and discouraged to call this function + * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary + * are likely to remove the mode argument and have it implicitly + * set to MBEDTLS_RSA_PUBLIC. + * + * \note Alternative implementations of RSA need not support + * mode being set to MBEDTLS_RSA_PRIVATE and may instead + * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code * * \note The output buffer must be as large as the size @@ -327,13 +355,22 @@ int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx, * \param output buffer that will hold the plaintext * \param output_max_len maximum length of the output buffer * + * \deprecated It is deprecated and discouraged to call this function + * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary + * are likely to remove the mode argument and have it implicitly + * set to MBEDTLS_RSA_PRIVATE. + * + * \note Alternative implementations of RSA need not support + * mode being set to MBEDTLS_RSA_PUBLIC and may instead + * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code * * \note The output buffer length \c output_max_len should be * as large as the size ctx->len of ctx->N (eg. 128 bytes * if RSA-1024 is used) to be able to hold an arbitrary * decrypted message. If it is not large enough to hold - * the decryption of the particular ciphertext provided, + * the decryption of the particular ciphertext provided, * the function will return MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. * * \note The input buffer must be as large as the size @@ -359,13 +396,22 @@ int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, * \param output buffer that will hold the plaintext * \param output_max_len maximum length of the output buffer * + * \deprecated It is deprecated and discouraged to call this function + * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary + * are likely to remove the mode argument and have it implicitly + * set to MBEDTLS_RSA_PRIVATE. + * + * \note Alternative implementations of RSA need not support + * mode being set to MBEDTLS_RSA_PUBLIC and may instead + * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code * * \note The output buffer length \c output_max_len should be * as large as the size ctx->len of ctx->N (eg. 128 bytes * if RSA-1024 is used) to be able to hold an arbitrary * decrypted message. If it is not large enough to hold - * the decryption of the particular ciphertext provided, + * the decryption of the particular ciphertext provided, * the function will return MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. * * \note The input buffer must be as large as the size @@ -393,16 +439,25 @@ int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx, * \param output buffer that will hold the plaintext * \param output_max_len maximum length of the output buffer * + * \deprecated It is deprecated and discouraged to call this function + * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary + * are likely to remove the mode argument and have it implicitly + * set to MBEDTLS_RSA_PRIVATE. + * + * \note Alternative implementations of RSA need not support + * mode being set to MBEDTLS_RSA_PUBLIC and may instead + * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \return 0 if successful, or an MBEDTLS_ERR_RSA_XXX error code * * \note The output buffer length \c output_max_len should be * as large as the size ctx->len of ctx->N (eg. 128 bytes * if RSA-1024 is used) to be able to hold an arbitrary * decrypted message. If it is not large enough to hold - * the decryption of the particular ciphertext provided, + * the decryption of the particular ciphertext provided, * the function will return MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. * - * \note The input buffer must be as large as the size + * \note The input buffer must be as large as the size * of ctx->N (eg. 128 bytes if RSA-1024 is used). */ int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx, @@ -430,6 +485,15 @@ int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx, * \param hash buffer holding the message digest * \param sig buffer that will hold the ciphertext * + * \deprecated It is deprecated and discouraged to call this function + * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary + * are likely to remove the mode argument and have it implicitly + * set to MBEDTLS_RSA_PRIVATE. + * + * \note Alternative implementations of RSA need not support + * mode being set to MBEDTLS_RSA_PUBLIC and may instead + * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \return 0 if the signing operation was successful, * or an MBEDTLS_ERR_RSA_XXX error code * @@ -460,6 +524,15 @@ int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx, * \param hash buffer holding the message digest * \param sig buffer that will hold the ciphertext * + * \deprecated It is deprecated and discouraged to call this function + * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary + * are likely to remove the mode argument and have it implicitly + * set to MBEDTLS_RSA_PRIVATE. + * + * \note Alternative implementations of RSA need not support + * mode being set to MBEDTLS_RSA_PUBLIC and may instead + * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \return 0 if the signing operation was successful, * or an MBEDTLS_ERR_RSA_XXX error code * @@ -488,6 +561,15 @@ int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx, * \param hash buffer holding the message digest * \param sig buffer that will hold the ciphertext * + * \deprecated It is deprecated and discouraged to call this function + * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary + * are likely to remove the mode argument and have it implicitly + * set to MBEDTLS_RSA_PRIVATE. + * + * \note Alternative implementations of RSA need not support + * mode being set to MBEDTLS_RSA_PUBLIC and may instead + * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \return 0 if the signing operation was successful, * or an MBEDTLS_ERR_RSA_XXX error code * @@ -522,6 +604,15 @@ int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx, * \param hash buffer holding the message digest * \param sig buffer holding the ciphertext * + * \deprecated It is deprecated and discouraged to call this function + * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary + * are likely to remove the mode argument and have it implicitly + * set to MBEDTLS_RSA_PUBLIC. + * + * \note Alternative implementations of RSA need not support + * mode being set to MBEDTLS_RSA_PRIVATE and may instead + * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \return 0 if the verify operation was successful, * or an MBEDTLS_ERR_RSA_XXX error code * @@ -552,6 +643,15 @@ int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx, * \param hash buffer holding the message digest * \param sig buffer holding the ciphertext * + * \deprecated It is deprecated and discouraged to call this function + * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary + * are likely to remove the mode argument and have it implicitly + * set to MBEDTLS_RSA_PUBLIC. + * + * \note Alternative implementations of RSA need not support + * mode being set to MBEDTLS_RSA_PRIVATE and may instead + * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \return 0 if the verify operation was successful, * or an MBEDTLS_ERR_RSA_XXX error code * @@ -580,6 +680,15 @@ int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx, * \param hash buffer holding the message digest * \param sig buffer holding the ciphertext * + * \deprecated It is deprecated and discouraged to call this function + * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary + * are likely to remove the mode argument and have it implicitly + * set to MBEDTLS_RSA_PUBLIC. + * + * \note Alternative implementations of RSA need not support + * mode being set to MBEDTLS_RSA_PRIVATE and may instead + * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * * \return 0 if the verify operation was successful, * or an MBEDTLS_ERR_RSA_XXX error code * diff --git a/library/error.c b/library/error.c index db42381c4..0217767cc 100644 --- a/library/error.c +++ b/library/error.c @@ -331,6 +331,8 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen ) mbedtls_snprintf( buf, buflen, "RSA - The output buffer for decryption is not large enough" ); if( use_ret == -(MBEDTLS_ERR_RSA_RNG_FAILED) ) mbedtls_snprintf( buf, buflen, "RSA - The random generator failed to generate non-zeros" ); + if( use_ret == -(MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION) ) + mbedtls_snprintf( buf, buflen, "RSA - The implementation doesn't provide the requested operation" ); #endif /* MBEDTLS_RSA_C */ #if defined(MBEDTLS_SSL_TLS_C)