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.
diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index 7d7469d..2ffb7ab 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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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 @@
* \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
*