From ad7581fac577fb1d69901e3a47fc5144bb4f9f1e Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Mon, 17 Dec 2018 09:43:21 +0000 Subject: [PATCH] Minor improvements to ChaCha20/Poly1305/ChaChaPoly documentation --- include/mbedtls/chacha20.h | 27 +++++++++++--------- include/mbedtls/chachapoly.h | 49 ++++++++++++++++++++---------------- include/mbedtls/poly1305.h | 33 +++++++++++++----------- 3 files changed, 60 insertions(+), 49 deletions(-) diff --git a/include/mbedtls/chacha20.h b/include/mbedtls/chacha20.h index 1c6cde07b..2ae5e6e5f 100644 --- a/include/mbedtls/chacha20.h +++ b/include/mbedtls/chacha20.h @@ -88,9 +88,10 @@ mbedtls_chacha20_context; void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx ); /** - * \brief This function releases and clears the specified ChaCha20 context. + * \brief This function releases and clears the specified + * ChaCha20 context. * - * \param ctx The ChaCha20 context to clear. May be \c NULL, + * \param ctx The ChaCha20 context to clear. This may be \c NULL, * in which case this function is a no-op. If it is not * \c NULL, it must point to an initialized context. * @@ -107,7 +108,8 @@ void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx ); * * \param ctx The ChaCha20 context to which the key should be bound. * It must be initialized. - * \param key The encryption/decryption key. Must be 32 bytes in length. + * \param key The encryption/decryption key. This must be \c 32 Bytes + * in length. * * \return \c 0 on success. * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL. @@ -127,8 +129,8 @@ int mbedtls_chacha20_setkey( mbedtls_chacha20_context *ctx, * * \param ctx The ChaCha20 context to which the nonce should be bound. * It must be initialized and bound to a key. - * \param nonce The nonce. Must be 12 bytes in size. - * \param counter The initial counter value. This is usually 0. + * \param nonce The nonce. This must be \c 12 Bytes in size. + * \param counter The initial counter value. This is usually \c 0. * * \return \c 0 on success. * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is @@ -157,11 +159,11 @@ int mbedtls_chacha20_starts( mbedtls_chacha20_context* ctx, * * \param ctx The ChaCha20 context to use for encryption or decryption. * It must be initialized and bound to a key and nonce. - * \param size The length of the input data in bytes. + * \param size The length of the input data in Bytes. * \param input The buffer holding the input data. * 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 must be able to hold \p size Bytes. * This pointer can be \c NULL if `size == 0`. * * \return \c 0 on success. @@ -186,14 +188,15 @@ int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx, * \note The \p input and \p output pointers must either be equal or * point to non-overlapping buffers. * - * \param key The encryption/decryption key. Must be 32 bytes in length. - * \param nonce The nonce. Must be 12 bytes in size. - * \param counter The initial counter value. This is usually 0. - * \param size The length of the input data in bytes. + * \param key The encryption/decryption key. + * This must be \c 32 Bytes in length. + * \param nonce The nonce. This must be \c 12 Bytes in size. + * \param counter The initial counter value. This is usually \c 0. + * \param size The length of the input data in Bytes. * \param input The buffer holding the input data. * 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 must be able to hold \p size Bytes. * This pointer can be \c NULL if `size == 0`. * * \return \c 0 on success. diff --git a/include/mbedtls/chachapoly.h b/include/mbedtls/chachapoly.h index 80d20e54a..49e615d27 100644 --- a/include/mbedtls/chachapoly.h +++ b/include/mbedtls/chachapoly.h @@ -123,7 +123,7 @@ void mbedtls_chachapoly_init( mbedtls_chachapoly_context *ctx ); * \brief This function releases and clears the specified * ChaCha20-Poly1305 context. * - * \param ctx The ChachaPoly context to clear. May be \c NULL, in which + * \param ctx The ChachaPoly context to clear. This may be \c NULL, in which * case this function is a no-op. */ void mbedtls_chachapoly_free( mbedtls_chachapoly_context *ctx ); @@ -133,8 +133,8 @@ void mbedtls_chachapoly_free( mbedtls_chachapoly_context *ctx ); * symmetric encryption key. * * \param ctx The ChaCha20-Poly1305 context to which the key should be - * bound. Must be initialized. - * \param key The 256-bit (32 bytes) key. + * bound. This must be initialized. + * \param key The \c 256 Bit (\c 32 Bytes) key. * * \return \c 0 on success. * \return A negative error code on failure. @@ -157,8 +157,10 @@ 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. Must be initialized. - * \param nonce The nonce/IV to use for the message. Must be 12 bytes. + * \param ctx The ChaCha20-Poly1305 context. This must be initialized + * and bound to a key. + * \param nonce The nonce/IV to use for the message. + * This must be a redable buffer of length \c 12 Bytes. * \param mode The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or * #MBEDTLS_CHACHAPOLY_DECRYPT (discouraged, see warning). * @@ -194,11 +196,12 @@ int mbedtls_chachapoly_starts( 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 aad_len The length (in bytes) of the AAD. The length has no + * \param ctx The ChaCha20-Poly1305 context. This must be initialized + * and bound to a key. + * \param aad_len The length in Bytes of the AAD. The length has no * restrictions. * \param aad Buffer containing the AAD. - * This pointer can be NULL if aad_len == 0. + * This pointer can be \c NULL if `aad_len == 0`. * * \return \c 0 on success. * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA @@ -228,12 +231,12 @@ 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. Must be initialized. + * \param ctx The ChaCha20-Poly1305 context to use. This 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 \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. + * written. This must be able to hold \p len bytes. * This pointer can be \c NULL if `len == 0`. * * \return \c 0 on success. @@ -251,7 +254,7 @@ 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. Must be initialized. + * \param ctx The ChaCha20-Poly1305 context to use. This 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 @@ -279,17 +282,18 @@ int mbedtls_chachapoly_finish( mbedtls_chachapoly_context *ctx, * and key. * * \param ctx The ChaCha20-Poly1305 context to use (holds the key). - * Must be initialized. + * This 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 \c NULL if `aad_len == 0`. + * \param aad The buffer containing the additional authenticated + * data (AAD). 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 \c NULL if `ilen == 0`. - * \param output The buffer to where the encrypted or decrypted data is written. - * This pointer can be \c NULL if `ilen == 0`. - * \param tag The buffer to where the computed 128-bit (16 bytes) MAC is written. + * \param output The buffer to where the encrypted or decrypted data + * is written. This pointer can be \c NULL if `ilen == 0`. + * \param tag The buffer to where the computed 128-bit (16 bytes) MAC + * is written. This must not be \c NULL. * * \return \c 0 on success. * \return A negative error code on failure. @@ -311,16 +315,17 @@ int mbedtls_chachapoly_encrypt_and_tag( mbedtls_chachapoly_context *ctx, * \c mbedtls_chachapoly_setkey(). * * \param ctx The ChaCha20-Poly1305 context to use (holds the key). - * \param length The length (in bytes) of the data to decrypt. - * \param nonce The 96-bit (12 bytes) nonce/IV to use. + * \param length The length (in Bytes) of the data to decrypt. + * \param nonce The \c 96 Bit (\c 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 tag The buffer holding the authentication tag. + * This must be a readable buffer of length \c 16 Bytes. * \param input The buffer containing the data to 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 decrypted data is written. - * 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_CHACHAPOLY_AUTH_FAILED diff --git a/include/mbedtls/poly1305.h b/include/mbedtls/poly1305.h index 617958e11..05866a2da 100644 --- a/include/mbedtls/poly1305.h +++ b/include/mbedtls/poly1305.h @@ -84,15 +84,18 @@ mbedtls_poly1305_context; * \c mbedtls_poly1305_finish(), then finally * \c mbedtls_poly1305_free(). * - * \param ctx The Poly1305 context to initialize. Must not be \c NULL. + * \param ctx The Poly1305 context to initialize. This must + * not be \c NULL. */ void mbedtls_poly1305_init( mbedtls_poly1305_context *ctx ); /** - * \brief This function releases and clears the specified Poly1305 context. + * \brief This function releases and clears the specified + * Poly1305 context. * - * \param ctx The Poly1305 context to clear. May be \c NULL, in which - * case this function is a no-op. + * \param ctx The Poly1305 context to clear. This may be \c NULL, in which + * case this function is a no-op. If it is not \c NULL, it must + * point to an initialized Poly1305 context. */ void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx ); @@ -103,8 +106,8 @@ void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx ); * invocation of Poly1305. * * \param ctx The Poly1305 context to which the key should be bound. - * Must be initialized. - * \param key The buffer containing the 32-byte (256-bit) key. + * This must be initialized. + * \param key The buffer containing the \c 32 Byte (\c 256 Bit) key. * * \return \c 0 on success. * \return A negative error code on failure. @@ -121,8 +124,8 @@ 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. - * Must be initialized. - * \param ilen The length of the input data (in bytes). + * This must be initialized and bound to a 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 \c NULL if `ilen == 0`. @@ -139,9 +142,9 @@ 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. + * This must be initialized and bound to a key. + * \param mac The buffer to where the MAC is written. This must + * be a writable buffer of length \c 16 Bytes. * * \return \c 0 on success. * \return A negative error code on failure. @@ -156,13 +159,13 @@ 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 32-byte (256-bit) key. - * \param ilen The length of the input data (in bytes). + * \param key The buffer containing the \c 32 Byte (\c 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 \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. + * \param mac The buffer to where the MAC is written. This must be + * a writable buffer of length \c 16 Bytes. * * \return \c 0 on success. * \return A negative error code on failure.