From b3c10b348bd99548c3263811508d3f41a74d7a7c Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Tue, 11 Dec 2018 14:52:01 +0000 Subject: [PATCH] Add documentation on parameter preconditions to ChaChaPoly modules --- include/mbedtls/chacha20.h | 22 ++++++++------- include/mbedtls/chachapoly.h | 52 +++++++++++++++++------------------- include/mbedtls/poly1305.h | 34 ++++++++++++----------- 3 files changed, 55 insertions(+), 53 deletions(-) diff --git a/include/mbedtls/chacha20.h b/include/mbedtls/chacha20.h index 529f22d9c..14436d68c 100644 --- a/include/mbedtls/chacha20.h +++ b/include/mbedtls/chacha20.h @@ -82,14 +82,15 @@ mbedtls_chacha20_context; * to \c mbedtls_chacha20_update(), and finally to * \c mbedtls_chacha20_free(). * - * \param ctx The ChaCha20 context to initialize. + * \param ctx The ChaCha20 context to initialize. Must not be \c NULL. */ void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx ); /** * \brief This function releases and clears the specified ChaCha20 context. * - * \param ctx The ChaCha20 context to clear. + * \param ctx The ChaCha20 context to clear. May be \c NULL, + * in which case this function is a no-op. */ void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx ); @@ -102,6 +103,7 @@ void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx ); * \c mbedtls_chacha_update(). * * \param ctx The ChaCha20 context to which the key should be bound. + * Must be initialized. * \param key The encryption/decryption key. Must be 32 bytes in length. * * \return \c 0 on success. @@ -121,6 +123,7 @@ int mbedtls_chacha20_setkey( mbedtls_chacha20_context *ctx, * messages encrypted with the same nonce and key. * * \param ctx The ChaCha20 context to which the nonce should be bound. + * Must be initialized. * \param nonce The nonce. Must be 12 bytes in size. * \param counter The initial counter value. This is usually 0. * @@ -150,16 +153,16 @@ int mbedtls_chacha20_starts( mbedtls_chacha20_context* ctx, * key and nonce. * * \param ctx The ChaCha20 context to use for encryption or decryption. + * Must be initialized. * \param size The length of the input data in bytes. * \param input The buffer holding the input data. - * This pointer can be NULL if size == 0. + * This pointer can be \c NULL if `size == 0`. * \param output The buffer holding the output data. * Must be able to hold \p size bytes. - * This pointer can be NULL if size == 0. + * This pointer can be \c NULL if `size == 0`. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if the ctx, input, or - * output pointers are NULL. + * \return A negative error code on failure. */ int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx, size_t size, @@ -185,14 +188,13 @@ int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx, * \param counter The initial counter value. This is usually 0. * \param size The length of the input data in bytes. * \param input The buffer holding the input data. - * This pointer can be NULL if size == 0. + * This pointer can be \c NULL if `size == 0`. * \param output The buffer holding the output data. * Must be able to hold \p size bytes. - * This pointer can be NULL if size == 0. + * This pointer can be \c NULL if `size == 0`. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if key, nonce, input, - * or output is NULL. + * \return A negative error code on failure. */ int mbedtls_chacha20_crypt( const unsigned char key[32], const unsigned char nonce[12], diff --git a/include/mbedtls/chachapoly.h b/include/mbedtls/chachapoly.h index 7de6f4e8c..80d20e54a 100644 --- a/include/mbedtls/chachapoly.h +++ b/include/mbedtls/chachapoly.h @@ -115,27 +115,29 @@ mbedtls_chachapoly_context; * all previous outputs of \c mbedtls_chachapoly_update(), * otherwise you can now safely use the plaintext. * - * \param ctx The ChachaPoly context to initialize. + * \param ctx The ChachaPoly context to initialize. Must not be \c NULL. */ void mbedtls_chachapoly_init( mbedtls_chachapoly_context *ctx ); /** - * \brief This function releases and clears the specified ChaCha20-Poly1305 context. + * \brief This function releases and clears the specified + * ChaCha20-Poly1305 context. * - * \param ctx The ChachaPoly context to clear. + * \param ctx The ChachaPoly context to clear. May be \c NULL, in which + * case this function is a no-op. */ void mbedtls_chachapoly_free( mbedtls_chachapoly_context *ctx ); /** - * \brief This function sets the ChaCha20-Poly1305 symmetric encryption key. + * \brief This function sets the ChaCha20-Poly1305 + * symmetric encryption key. * * \param ctx The ChaCha20-Poly1305 context to which the key should be - * bound. + * bound. Must be initialized. * \param key The 256-bit (32 bytes) key. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA - * if \p ctx or \p key are NULL. + * \return A negative error code on failure. */ int mbedtls_chachapoly_setkey( mbedtls_chachapoly_context *ctx, const unsigned char key[32] ); @@ -155,14 +157,13 @@ int mbedtls_chachapoly_setkey( mbedtls_chachapoly_context *ctx, * \warning Decryption with the piecewise API is discouraged, see the * warning on \c mbedtls_chachapoly_init(). * - * \param ctx The ChaCha20-Poly1305 context. + * \param ctx The ChaCha20-Poly1305 context. Must be initialized. * \param nonce The nonce/IV to use for the message. Must be 12 bytes. * \param mode The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or * #MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning). * * \return \c 0 on success. - * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA - * if \p ctx or \p mac are NULL. + * \return A negative error code on failure. */ int mbedtls_chachapoly_starts( mbedtls_chachapoly_context *ctx, const unsigned char nonce[12], @@ -227,20 +228,19 @@ int mbedtls_chachapoly_update_aad( mbedtls_chachapoly_context *ctx, * \warning Decryption with the piecewise API is discouraged, see the * warning on \c mbedtls_chachapoly_init(). * - * \param ctx The ChaCha20-Poly1305 context to use. + * \param ctx The ChaCha20-Poly1305 context to use. Must be initialized. * \param len The length (in bytes) of the data to encrypt or decrypt. * \param input The buffer containing the data to encrypt or decrypt. - * This pointer can be NULL if len == 0. - * \param output The buffer to where the encrypted or decrypted data is written. - * Must be able to hold \p len bytes. - * This pointer can be NULL if len == 0. + * This pointer can be \c NULL if `len == 0`. + * \param output The buffer to where the encrypted or decrypted data is + * written. Must be able to hold \p len bytes. + * This pointer can be \c NULL if `len == 0`. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA - * if \p ctx, \p input, or \p output are NULL. * \return #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE * if the operation has not been started or has been * finished. + * \return Another negative error code on other kinds of failure. */ int mbedtls_chachapoly_update( mbedtls_chachapoly_context *ctx, size_t len, @@ -251,18 +251,17 @@ int mbedtls_chachapoly_update( mbedtls_chachapoly_context *ctx, * \brief This function finished the ChaCha20-Poly1305 operation and * generates the MAC (authentication tag). * - * \param ctx The ChaCha20-Poly1305 context to use. + * \param ctx The ChaCha20-Poly1305 context to use. Must be initialized. * \param mac The buffer to where the 128-bit (16 bytes) MAC is written. * * \warning Decryption with the piecewise API is discouraged, see the * warning on \c mbedtls_chachapoly_init(). * * \return \c 0 on success. - * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA - * if \p ctx or \p mac are NULL. * \return #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE * if the operation has not been started or has been * finished. + * \return Another negative error code on other kinds of failure. */ int mbedtls_chachapoly_finish( mbedtls_chachapoly_context *ctx, unsigned char mac[16] ); @@ -280,20 +279,20 @@ int mbedtls_chachapoly_finish( mbedtls_chachapoly_context *ctx, * and key. * * \param ctx The ChaCha20-Poly1305 context to use (holds the key). + * Must be initialized. * \param length The length (in bytes) of the data to encrypt or decrypt. * \param nonce The 96-bit (12 bytes) nonce/IV to use. * \param aad The buffer containing the additional authenticated data (AAD). - * This pointer can be NULL if aad_len == 0. + * This pointer can be \c NULL if `aad_len == 0`. * \param aad_len The length (in bytes) of the AAD data to process. * \param input The buffer containing the data to encrypt or decrypt. - * This pointer can be NULL if ilen == 0. + * This pointer can be \c NULL if `ilen == 0`. * \param output The buffer to where the encrypted or decrypted data is written. - * This pointer can be NULL if ilen == 0. + * This pointer can be \c NULL if `ilen == 0`. * \param tag The buffer to where the computed 128-bit (16 bytes) MAC is written. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA - * if one or more of the required parameters are NULL. + * \return A negative error code on failure. */ int mbedtls_chachapoly_encrypt_and_tag( mbedtls_chachapoly_context *ctx, size_t length, @@ -324,10 +323,9 @@ int mbedtls_chachapoly_encrypt_and_tag( mbedtls_chachapoly_context *ctx, * This pointer can be NULL if ilen == 0. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA - * if one or more of the required parameters are NULL. * \return #MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED * if the data was not authentic. + * \return Another negative error code on other kinds of failure. */ int mbedtls_chachapoly_auth_decrypt( mbedtls_chachapoly_context *ctx, size_t length, diff --git a/include/mbedtls/poly1305.h b/include/mbedtls/poly1305.h index b02f968b5..617958e11 100644 --- a/include/mbedtls/poly1305.h +++ b/include/mbedtls/poly1305.h @@ -84,14 +84,15 @@ mbedtls_poly1305_context; * \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 @@ void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx ); * 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 @@ int mbedtls_poly1305_starts( mbedtls_poly1305_context *ctx, * 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 @@ int mbedtls_poly1305_update( mbedtls_poly1305_context *ctx, * 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 @@ int mbedtls_poly1305_finish( mbedtls_poly1305_context *ctx, * \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,