Improve documentation of PKCS1 decryption functions
Document the preconditions on the input and output buffers for
the PKCS1 decryption functions
- mbedtls_rsa_pkcs1_decrypt,
- mbedtls_rsa_rsaes_pkcs1_v15_decrypt
- mbedtls_rsa_rsaes_oaep_decrypt
diff --git a/include/polarssl/rsa.h b/include/polarssl/rsa.h
index e80bb4d..7d64f93 100644
--- a/include/polarssl/rsa.h
+++ b/include/polarssl/rsa.h
@@ -336,9 +336,15 @@
*
* \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
*
- * \note The output buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise
- * an error is thrown.
+ * \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 function will return POLARSSL_ERR_RSA_OUTPUT_TOO_LARGE.
+ *
+ * \note The input buffer must be as large as the size
+ * of ctx->N (eg. 128 bytes if RSA-1024 is used).
*/
int rsa_pkcs1_decrypt( rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -363,9 +369,15 @@
*
* \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
*
- * \note The output buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise
- * an error is thrown.
+ * \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 function will return POLARSSL_ERR_RSA_OUTPUT_TOO_LARGE.
+ *
+ * \note The input buffer must be as large as the size
+ * of ctx->N (eg. 128 bytes if RSA-1024 is used).
*/
int rsa_rsaes_pkcs1_v15_decrypt( rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -392,9 +404,15 @@
*
* \return 0 if successful, or an POLARSSL_ERR_RSA_XXX error code
*
- * \note The output buffer must be as large as the size
- * of ctx->N (eg. 128 bytes if RSA-1024 is used) otherwise
- * an error is thrown.
+ * \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 function will return POLARSSL_ERR_RSA_OUTPUT_TOO_LARGE.
+ *
+ * \note The input buffer must be as large as the size
+ * of ctx->N (eg. 128 bytes if RSA-1024 is used).
*/
int rsa_rsaes_oaep_decrypt( rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),