md: Add parameter validation
Improve documentation on parameter constraints
diff --git a/include/mbedtls/md.h b/include/mbedtls/md.h
index 8bcf766..e860de2 100644
--- a/include/mbedtls/md.h
+++ b/include/mbedtls/md.h
@@ -109,7 +109,7 @@
* \brief This function returns the message-digest information
* associated with the given digest name.
*
- * \param md_name The name of the digest to search for.
+ * \param md_name The name of the digest to search for. This must not be \c NULL.
*
* \return The message-digest information associated with \p md_name.
* \return NULL if the associated message-digest information is not found.
@@ -120,7 +120,7 @@
* \brief This function returns the message-digest information
* associated with the given digest type.
*
- * \param md_type The type of digest to search for.
+ * \param md_type The type of digest to search for. This must not be \c NULL.
*
* \return The message-digest information associated with \p md_type.
* \return NULL if the associated message-digest information is not found.
@@ -133,7 +133,7 @@
*
* This function should always be called first. It prepares the
* context for mbedtls_md_setup() for binding it to a
- * message-digest algorithm.
+ * message-digest algorithm. The \p ctx must not be \c NULL.
*/
void mbedtls_md_init( mbedtls_md_context_t *ctx );
@@ -148,7 +148,7 @@
* Calling this function if you have previously
* called mbedtls_md_init() and nothing else is optional.
* You must not call this function if you have not called
- * mbedtls_md_init().
+ * mbedtls_md_init(). The \p ctx must not be \c NULL.
*/
void mbedtls_md_free( mbedtls_md_context_t *ctx );
@@ -167,7 +167,7 @@
*
* \deprecated Superseded by mbedtls_md_setup() in 2.0.0
*
- * \param ctx The context to set up.
+ * \param ctx The context to set up. This must not be \c NULL.
* \param md_info The information structure of the message-digest algorithm
* to use.
*
@@ -188,9 +188,9 @@
* mbedtls_md_free(). Makes it necessary to call
* mbedtls_md_free() later.
*
- * \param ctx The context to set up.
+ * \param ctx The context to set up. This must not be \c NULL.
* \param md_info The information structure of the message-digest algorithm
- * to use.
+ * to use. This must not be \c NULL.
* \param hmac Defines if HMAC is used. 0: HMAC is not used (saves some memory),
* or non-zero: HMAC is used with this context.
*
@@ -214,8 +214,8 @@
* \warning This function clones the message-digest state, not the
* HMAC state.
*
- * \param dst The destination context.
- * \param src The context to be cloned.
+ * \param dst The destination context. This must not be \c NULL.
+ * \param src The context to be cloned. This must not be \c NULL.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.
@@ -228,7 +228,7 @@
* message-digest information structure.
*
* \param md_info The information structure of the message-digest algorithm
- * to use.
+ * to use. This must not be \c NULL.
*
* \return The size of the message-digest output in Bytes.
*/
@@ -239,7 +239,7 @@
* message-digest information structure.
*
* \param md_info The information structure of the message-digest algorithm
- * to use.
+ * to use. This must not be \c NULL.
*
* \return The type of the message digest.
*/
@@ -250,7 +250,7 @@
* message-digest information structure.
*
* \param md_info The information structure of the message-digest algorithm
- * to use.
+ * to use. This must not be \c NULL.
*
* \return The name of the message digest.
*/
@@ -280,7 +280,7 @@
* Afterwards, call mbedtls_md_finish().
*
* \param ctx The generic message-digest context.
- * \param input The buffer holding the input data.
+ * \param input The buffer holding the input data. This must not be \c NULL.
* \param ilen The length of the input data.
*
* \return \c 0 on success.
@@ -302,6 +302,7 @@
*
* \param ctx The generic message-digest context.
* \param output The buffer for the generic message-digest checksum result.
+ * This must not be \c NULL.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
@@ -318,10 +319,11 @@
* Output = message_digest(input buffer).
*
* \param md_info The information structure of the message-digest algorithm
- * to use.
+ * to use. This must not be \c NULL.
* \param input The buffer holding the data.
* \param ilen The length of the input data.
* \param output The generic message-digest checksum result.
+ * This must not be \c NULL.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
@@ -339,9 +341,10 @@
* Output = message_digest(file contents).
*
* \param md_info The information structure of the message-digest algorithm
- * to use.
- * \param path The input file name.
+ * to use. This must not be \c NULL.
+ * \param path The input file name. This must not be \c NULL.
* \param output The generic message-digest checksum result.
+ * This must not be \c NULL.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing
@@ -363,7 +366,7 @@
*
* \param ctx The message digest context containing an embedded HMAC
* context.
- * \param key The HMAC secret key.
+ * \param key The HMAC secret key. This must not be \c NULL.
* \param keylen The length of the HMAC key in Bytes.
*
* \return \c 0 on success.
@@ -407,7 +410,7 @@
*
* \param ctx The message digest context containing an embedded HMAC
* context.
- * \param output The generic HMAC checksum result.
+ * \param output The generic HMAC checksum result. This must not be \c NULL.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
@@ -424,7 +427,7 @@
* input.
*
* \param ctx The message digest context containing an embedded HMAC
- * context.
+ * context. This must not be \c NULL.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
@@ -443,12 +446,12 @@
* output = generic HMAC(hmac key, input buffer).
*
* \param md_info The information structure of the message-digest algorithm
- * to use.
- * \param key The HMAC secret key.
+ * to use. This must not be \c NULL.
+ * \param key The HMAC secret key. This must not be \c NULL.
* \param keylen The length of the HMAC secret key in Bytes.
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
- * \param output The generic HMAC result.
+ * \param output The generic HMAC result. This must not be \c NULL.
*
* \return \c 0 on success.
* \return #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification