From 573bb96416057b19fb6c50e84d6c1b97ade1cf17 Mon Sep 17 00:00:00 2001
From: Simon Butcher <simon.butcher@arm.com>
Date: Wed, 19 Jul 2017 01:58:47 +0100
Subject: [PATCH] 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
---
 include/polarssl/rsa.h | 36 +++++++++++++++++++++++++++---------
 1 file changed, 27 insertions(+), 9 deletions(-)

diff --git a/include/polarssl/rsa.h b/include/polarssl/rsa.h
index e80bb4da0..7d64f939a 100644
--- a/include/polarssl/rsa.h
+++ b/include/polarssl/rsa.h
@@ -336,9 +336,15 @@ int rsa_rsaes_oaep_encrypt( rsa_context *ctx,
  *
  * \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 @@ int rsa_pkcs1_decrypt( rsa_context *ctx,
  *
  * \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 @@ int rsa_rsaes_pkcs1_v15_decrypt( rsa_context *ctx,
  *
  * \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),