Add documentation on parameter preconditions to ChaChaPoly modules
diff --git a/include/mbedtls/poly1305.h b/include/mbedtls/poly1305.h
index b02f968..617958e 100644
--- a/include/mbedtls/poly1305.h
+++ b/include/mbedtls/poly1305.h
@@ -84,14 +84,15 @@
* \c mbedtls_poly1305_finish(), then finally
* \c mbedtls_poly1305_free().
*
- * \param ctx The Poly1305 context to initialize.
+ * \param ctx The Poly1305 context to initialize. Must not be \c NULL.
*/
void mbedtls_poly1305_init( mbedtls_poly1305_context *ctx );
/**
* \brief This function releases and clears the specified Poly1305 context.
*
- * \param ctx The Poly1305 context to clear.
+ * \param ctx The Poly1305 context to clear. May be \c NULL, in which
+ * case this function is a no-op.
*/
void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx );
@@ -102,11 +103,11 @@
* invocation of Poly1305.
*
* \param ctx The Poly1305 context to which the key should be bound.
- * \param key The buffer containing the 256-bit key.
+ * Must be initialized.
+ * \param key The buffer containing the 32-byte (256-bit) key.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if ctx or key are NULL.
+ * \return A negative error code on failure.
*/
int mbedtls_poly1305_starts( mbedtls_poly1305_context *ctx,
const unsigned char key[32] );
@@ -120,13 +121,14 @@
* It can be called repeatedly to process a stream of data.
*
* \param ctx The Poly1305 context to use for the Poly1305 operation.
- * \param ilen The length of the input data (in bytes). Any value is accepted.
+ * Must be initialized.
+ * \param ilen The length of the input data (in bytes).
+ * Any value is accepted.
* \param input The buffer holding the input data.
- * This pointer can be NULL if ilen == 0.
+ * This pointer can be \c NULL if `ilen == 0`.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if ctx or input are NULL.
+ * \return A negative error code on failure.
*/
int mbedtls_poly1305_update( mbedtls_poly1305_context *ctx,
const unsigned char *input,
@@ -137,12 +139,12 @@
* Authentication Code (MAC).
*
* \param ctx The Poly1305 context to use for the Poly1305 operation.
+ * Must be initialized.
* \param mac The buffer to where the MAC is written. Must be big enough
* to hold the 16-byte MAC.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if ctx or mac are NULL.
+ * \return A negative error code on failure.
*/
int mbedtls_poly1305_finish( mbedtls_poly1305_context *ctx,
unsigned char mac[16] );
@@ -154,16 +156,16 @@
* \warning The key must be unique and unpredictable for each
* invocation of Poly1305.
*
- * \param key The buffer containing the 256-bit key.
- * \param ilen The length of the input data (in bytes). Any value is accepted.
+ * \param key The buffer containing the 32-byte (256-bit) key.
+ * \param ilen The length of the input data (in bytes).
+ * Any value is accepted.
* \param input The buffer holding the input data.
- * This pointer can be NULL if ilen == 0.
+ * This pointer can be \c NULL if `ilen == 0`.
* \param mac The buffer to where the MAC is written. Must be big enough
* to hold the 16-byte MAC.
*
* \return \c 0 on success.
- * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
- * if key, input, or mac are NULL.
+ * \return A negative error code on failure.
*/
int mbedtls_poly1305_mac( const unsigned char key[32],
const unsigned char *input,