From b500f8b9113a54e194a116338eb9b606c4628d45 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 8 May 2018 12:43:48 +0200 Subject: [PATCH] Update documentation to match new guidelines. --- include/mbedtls/chacha20.h | 157 ++++++++++-------- include/mbedtls/chachapoly.h | 297 +++++++++++++++++++++-------------- include/mbedtls/cipher.h | 6 +- include/mbedtls/poly1305.h | 124 +++++++++------ 4 files changed, 350 insertions(+), 234 deletions(-) diff --git a/include/mbedtls/chacha20.h b/include/mbedtls/chacha20.h index d32da1b77..579ea3888 100644 --- a/include/mbedtls/chacha20.h +++ b/include/mbedtls/chacha20.h @@ -1,11 +1,18 @@ /** * \file chacha20.h * - * \brief ChaCha20 cipher. + * \brief This file contains ChaCha20 definitions and functions. + * + * ChaCha20 is a stream cipher that can encrypt and decrypt + * information. ChaCha was created by Daniel Bernstein as a variant of + * its Salsa cipher https://cr.yp.to/chacha/chacha-20080128.pdf + * ChaCha20 is the variant with 20 rounds, that was also standardized + * in RFC 7539. * * \author Daniel King - * - * Copyright (C) 2006-2016, ARM Limited, All Rights Reserved + */ + +/* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved. * SPDX-License-Identifier: Apache-2.0 * * Licensed under the Apache License, Version 2.0 (the "License"); you may @@ -20,8 +27,9 @@ * See the License for the specific language governing permissions and * limitations under the License. * - * This file is part of mbed TLS (https://tls.mbed.org) + * This file is part of Mbed TLS (https://tls.mbed.org) */ + #ifndef MBEDTLS_CHACHA20_H #define MBEDTLS_CHACHA20_H @@ -44,10 +52,10 @@ extern "C" { typedef struct { - uint32_t initial_state[16]; /*! Holds the initial state (before round operations) */ - uint32_t working_state[16]; /*! Holds the working state (after round operations) */ - uint8_t keystream8[64]; /*! Holds leftover keystream bytes */ - size_t keystream_bytes_used; /*! Number of keystream bytes currently used */ + uint32_t initial_state[16]; /*! The initial state (before round operations). */ + uint32_t working_state[16]; /*! The working state (after round operations). */ + uint8_t keystream8[64]; /*! Leftover keystream bytes. */ + size_t keystream_bytes_used; /*! Number of keystream bytes already used. */ } mbedtls_chacha20_context; @@ -56,118 +64,141 @@ mbedtls_chacha20_context; #endif /* MBEDTLS_CHACHA20_ALT */ /** - * \brief Initialize ChaCha20 context + * \brief This function initializes the specified ChaCha20 context. * - * \param ctx ChaCha20 context to be initialized + * It must be the first API called before using + * the context. + * + * It is usually followed by calls to + * \c mbedtls_chacha20_setkey() and + * \c mbedtls_chacha20_starts(), then one or more calls to + * to \c mbedtls_chacha20_update(), and finally to + * \c mbedtls_chacha20_free(). + * + * \param ctx The ChaCha20 context to initialize. */ void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx ); /** - * \brief Clear ChaCha20 context + * \brief This function releases and clears the specified ChaCha20 context. * - * \param ctx ChaCha20 context to be cleared + * \param ctx The ChaCha20 context to clear. */ void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx ); /** - * \brief Set the ChaCha20 key. + * \brief This function sets the encryption/decryption key. * - * \note The nonce and counter must be set after calling this function, - * before data can be encrypted/decrypted. The nonce and - * counter are set by calling mbedtls_chacha20_starts. + * \note After using this function, you must also call + * \c mbedtls_chacha20_starts() to set a nonce before you + * start encrypting/decrypting data with + * \c mbedtls_chacha_update(). * - * \see mbedtls_chacha20_starts + * \param ctx The ChaCha20 context to which the key should be bound. + * \param key The encryption/decryption key. Must be 32 bytes in length. * - * \param ctx The context to setup. - * \param key Buffer containing the 256-bit key. Must be 32 bytes in length. - * - * \return MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA is returned if ctx or key - * is NULL, or if key_bits is not 128 or 256. - * Otherwise, 0 is returned to indicate success. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL. */ int mbedtls_chacha20_setkey( mbedtls_chacha20_context *ctx, const unsigned char key[32] ); /** - * \brief Set the ChaCha20 nonce and initial counter value. + * \brief This function sets the nonce and initial counter value. * * \note A ChaCha20 context can be re-used with the same key by - * calling this function to change the nonce and/or initial - * counter value. + * calling this function to change the nonce. * - * \param ctx The ChaCha20 context. - * \param nonce Buffer containing the 96-bit nonce. Must be 12 bytes in size. - * \param counter Initial counter value to use. This is usually 0. + * \warning You must never use the same nonce twice with the same key. + * This would void any confidentiality guarantees for the + * messages encrypted with the same nonce and key. * - * \return MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA is returned if ctx or - * nonce is NULL. - * Otherwise, 0 is returned to indicate success. + * \param ctx The ChaCha20 context to which the nonce should be bound. + * \param nonce The nonce. Must be 12 bytes in size. + * \param counter The initial counter value. This is usually 0. + * + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is + * NULL. */ int mbedtls_chacha20_starts( mbedtls_chacha20_context* ctx, const unsigned char nonce[12], uint32_t counter ); /** - * \brief Encrypt or decrypt data. + * \brief This function encrypts or decrypts data. * - * This function is used to both encrypt and decrypt data. + * Since ChaCha20 is a stream cipher, the same operation is + * used for encrypting and decrypting data. * * \note The \p input and \p output pointers must either be equal or * point to non-overlapping buffers. * - * \note mbedtls_chacha20_setkey and mbedtls_chacha20_starts must be - * called at least once to setup the context before this function - * can be called. + * \note \c mbedtls_chacha20_setkey() and + * \c mbedtls_chacha20_starts() must be called at least once + * to setup the context before this function can be called. * - * \param ctx The ChaCha20 context. - * \param size The length (in bytes) to process. This can have any length. - * \param input Buffer containing the input data. + * \note This function can be called mutliple times in a row in + * order to encrypt of decrypt data piecewise with the same + * key and nonce. + * + * \param ctx The ChaCha20 context to use for encryption or decryption. + * \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. - * \param output Buffer containing the output data. + * \param output The buffer holding the output data. + * Must be able to hold \p size bytes. * This pointer can be NULL if size == 0. * - * \return MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if the ctx, input, or + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if the ctx, input, or * output pointers are NULL. - * Otherwise, 0 is returned to indicate success. */ int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx, - size_t size, - const unsigned char *input, - unsigned char *output ); + size_t size, + const unsigned char *input, + unsigned char *output ); /** - * \brief Encrypt or decrypt a message using ChaCha20. + * \brief This function encrypts or decrypts data with ChaCha20 and + * the given key and nonce. * - * This function is used the same way for encrypting and - * decrypting data. It's not necessary to specify which - * operation is being performed. + * Since ChaCha20 is a stream cipher, the same operation is + * used for encrypting and decrypting data. * - * \note The \p input and \p output buffers may overlap, but only - * if input >= output (i.e. only if input points ahead of - * the output pointer). + * \warning You must never use the same (key, nonce) pair more than + * once. This would void any confidentiality guarantees for + * the messages encrypted with the same nonce and key. * - * \param key Buffer containing the 256-bit key. Must be 32 bytes in length. - * \param nonce Buffer containing the 96-bit nonce. Must be 12 bytes in length. + * \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 data_len The number of bytes to process. - * \param input Buffer containing the input data (data to encrypt or decrypt). - * \param output Buffer to where the processed data is written. + * \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. + * \param output The buffer holding the output data. + * Must be able to hold \p size bytes. + * This pointer can be NULL if size == 0. * - * \return MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if key, nonce, input, + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if key, nonce, input, * or output is NULL. - * Otherwise, 0 is returned to indicate success. */ int mbedtls_chacha20_crypt( const unsigned char key[32], const unsigned char nonce[12], uint32_t counter, - size_t data_len, + size_t size, const unsigned char* input, unsigned char* output ); /** - * \brief Checkup routine + * \brief The ChaCha20 checkup routine. * - * \return 0 if successful, or 1 if the test failed + * \return \c 0 on success. + * \return \c 1 on failure. */ int mbedtls_chacha20_self_test( int verbose ); diff --git a/include/mbedtls/chachapoly.h b/include/mbedtls/chachapoly.h index e7413b36f..ddcd54972 100644 --- a/include/mbedtls/chachapoly.h +++ b/include/mbedtls/chachapoly.h @@ -1,9 +1,18 @@ /** * \file chachapoly.h * - * \brief ChaCha20-Poly1305 AEAD construction based on RFC 7539. + * \brief This file contains the AEAD-ChaCha20-Poly1305 definitions and + * functions. * - * Copyright (C) 2006-2016, ARM Limited, All Rights Reserved + * ChaCha20-Poly1305 is an algorithm for Authenticated Encryption + * with Associated Data (AEAD) that can be used to encrypt and + * authenticate data. It is based on ChaCha20 and Poly1305 by Daniel + * Bernstein and was standardized in RFC 7539. + * + * \author Daniel King + */ + +/* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved. * SPDX-License-Identifier: Apache-2.0 * * Licensed under the Apache License, Version 2.0 (the "License"); you may @@ -18,8 +27,9 @@ * See the License for the specific language governing permissions and * limitations under the License. * - * This file is part of mbed TLS (https://tls.mbed.org) + * This file is part of Mbed TLS (https://tls.mbed.org) */ + #ifndef MBEDTLS_CHACHAPOLY_H #define MBEDTLS_CHACHAPOLY_H @@ -30,7 +40,7 @@ #endif #define MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA -0x00047 /**< Invalid input parameter(s). */ -#define MBEDTLS_ERR_CHACHAPOLY_BAD_STATE -0x00049 /**< The requested operation is not permitted in the current state */ +#define MBEDTLS_ERR_CHACHAPOLY_BAD_STATE -0x00049 /**< The requested operation is not permitted in the current state. */ #define MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED -0x00049 /**< Authenticated decryption failed: data was not authentic. */ @@ -40,8 +50,8 @@ extern "C" { typedef enum { - MBEDTLS_CHACHAPOLY_ENCRYPT, - MBEDTLS_CHACHAPOLY_DECRYPT + MBEDTLS_CHACHAPOLY_ENCRYPT, /**< The mode value for performing encryption. */ + MBEDTLS_CHACHAPOLY_DECRYPT /**< The mode value for performing decryption. */ } mbedtls_chachapoly_mode_t; @@ -52,12 +62,12 @@ mbedtls_chachapoly_mode_t; typedef struct { - mbedtls_chacha20_context chacha20_ctx; /** ChaCha20 context */ - mbedtls_poly1305_context poly1305_ctx; /** Poly1305 context */ - uint64_t aad_len; /** Length (bytes) of the Additional Authenticated Data */ - uint64_t ciphertext_len; /** Length (bytes) of the ciphertext */ - int state; /** Current state of the context */ - mbedtls_chachapoly_mode_t mode; /** Cipher mode (encrypt or decrypt) */ + mbedtls_chacha20_context chacha20_ctx; /**< The ChaCha20 context. */ + mbedtls_poly1305_context poly1305_ctx; /**< The Poly1305 context. */ + uint64_t aad_len; /**< The length (bytes) of the Additional Authenticated Data. */ + uint64_t ciphertext_len; /**< The length (bytes) of the ciphertext. */ + int state; /**< The current state of the context. */ + mbedtls_chachapoly_mode_t mode; /**< Cipher mode (encrypt or decrypt). */ } mbedtls_chachapoly_context; @@ -66,112 +76,144 @@ mbedtls_chachapoly_context; #endif /* !MBEDTLS_CHACHAPOLY_ALT */ /** - * \brief Initialize ChaCha20-Poly1305 context + * \brief This function initializes the specified ChaCha20-Poly1305 context. * - * \param ctx ChaCha20-Poly1305 context to be initialized + * It must be the first API called before using + * the context. It must be followed by a call to + * \c mbedtls_chachapoly_setkey() before any operation can be + * done, and to \c mbedtls_chachapoly_free() once all + * operations with that context have been finished. + * + * In order to encrypt or decrypt full messages at once, for + * each message you should make a single call to + * \c mbedtls_chachapoly_crypt_and_tag() or + * \c mbedtls_chachapoly_auth_decrypt(). + * + * In order to encrypt or decrypt messages piecewise, for each + * message you should make a call to + * \c mbedtls_chachapoly_starts(), then 0 or more calls to + * \c mbedtls_chachapoly_update_aad(), then 0 or more calls to + * \c mbedtls_chachapoly_update(), then one call to + * \c mbedtls_chachapoly_finish(). + * + * + * \param ctx The ChachaPoly context to initialize. */ void mbedtls_chachapoly_init( mbedtls_chachapoly_context *ctx ); /** - * \brief Clear ChaCha20-Poly1305 context + * \brief This function releases and clears the specified ChaCha20-Poly1305 context. * - * \param ctx ChaCha20-Poly1305 context to be cleared + * \param ctx The ChachaPoly context to clear. */ void mbedtls_chachapoly_free( mbedtls_chachapoly_context *ctx ); /** - * \brief Set the ChaCha20-Poly1305 symmetric encryption key. + * \brief This function sets the ChaCha20-Poly1305 symmetric encryption key. * - * \param ctx The ChaCha20-Poly1305 context. - * \param key The 256-bit (32 bytes) key. + * \param ctx The ChaCha20-Poly1305 context to which the key should be + * bound. + * \param key The 256-bit (32 bytes) key. * - * \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned - * if \p ctx or \p key are NULL. - * Otherwise, 0 is returned to indicate success. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA + * if \p ctx or \p key are NULL. */ int mbedtls_chachapoly_setkey( mbedtls_chachapoly_context *ctx, const unsigned char key[32] ); /** - * \brief Setup ChaCha20-Poly1305 context for encryption or decryption. + * \brief This function starts a ChaCha20-Poly1305 encryption or + * decryption operation. * - * \note If the context is being used for AAD only (no data to - * encrypt or decrypt) then \p mode can be set to any value. + * \warning You must never use the same nonce twice with the same key. + * This would void any confidentiality and authenticity + * guarantees for the messages encrypted with the same nonce + * and key. * - * \param ctx The ChaCha20-Poly1305 context. - * \param nonce The nonce/IV to use for the message. This must be unique - * for every message encrypted under the same key. - * \param mode Specifies whether the context is used to encrypt or - * decrypt data. + * \note If the context is being used for AAD only (no data to + * encrypt or decrypt) then \p mode can be set to any value. * - * \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned - * if \p ctx or \p mac are NULL. - * Otherwise, 0 is returned to indicate success. + * \param ctx The ChaCha20-Poly1305 context. + * \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. + * + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA + * if \p ctx or \p mac are NULL. */ int mbedtls_chachapoly_starts( mbedtls_chachapoly_context *ctx, const unsigned char nonce[12], mbedtls_chachapoly_mode_t mode ); /** - * \brief Process additional authenticated data (AAD). + * \brief This function feeds additional data to be authenticated + * into an ongoing ChaCha20-Poly1305 operation. * - * This function processes data that is authenticated, but - * not encrypted. + * The Additional Authenticated Data (AAD), also called + * Associated Data (AD) is only authenticated but not + * encrypted nor included in the encrypted output. It is + * usually transmitted separately fro mthe ciphertext or + * computed locally by each party. * - * \note This function is called before data is encrypted/decrypted. - * I.e. call this function to process the AAD before calling - * mbedtls_chachapoly_update. + * \note This function is called before data is encrypted/decrypted. + * I.e. call this function to process the AAD before calling + * \c mbedtls_chachapoly_update(). * - * You may call this function multiple times to process - * an arbitrary amount of AAD. It is permitted to call - * this function 0 times, if no AAD is used. + * You may call this function multiple times to process + * an arbitrary amount of AAD. It is permitted to call + * this function 0 times, if no AAD is used. * - * This function cannot be called any more if data has - * been processed by mbedtls_chachapoly_update, - * or if the context has been finished. + * This function cannot be called any more if data has + * been processed by \c mbedtls_chachapoly_update(), + * or if the context has been finished. * - * \param ctx The ChaCha20-Poly1305 context. - * \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. + * \param ctx The ChaCha20-Poly1305 context to use. + * \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. * - * \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned - * if \p ctx or \p aad are NULL. - * MBEDTLS_ERR_CHACHAPOLY_BAD_STATE is returned if - * the context has not been setup, the context has been - * finished, or if the AAD has been finished. - * Otherwise, 0 is returned to indicate success. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA + * if \p ctx or \p aad are NULL. + * \return #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE + * if the operations has not been started or has been + * finished, or if the AAD has been finished. */ int mbedtls_chachapoly_update_aad( mbedtls_chachapoly_context *ctx, size_t aad_len, const unsigned char *aad ); /** - * \brief Encrypt/decrypt data. + * \brief Thus function feeds data to be encrypted or decrypted + * into an on-going ChaCha20-Poly1305 + * operation. * - * The direction (encryption or decryption) depends on the - * mode that was given when calling - * mbedtls_chachapoly_starts. + * The direction (encryption or decryption) depends on the + * mode that was given when calling + * \c mbedtls_chachapoly_starts(). * - * You may call this function multiple times to process - * an arbitrary amount of data. It is permitted to call - * this function 0 times, if no data is to be encrypted - * or decrypted. + * You may call this function multiple times to process + * an arbitrary amount of data. It is permitted to call + * this function 0 times, if no data is to be encrypted + * or decrypted. * - * \param ctx The ChaCha20-Poly1305 context. - * \param len The length (in bytes) of the data to encrypt or decrypt. - * \param input Buffer containing the data to encrypt or decrypt. - * This pointer can be NULL if len == 0. - * \param output Buffer to where the encrypted or decrypted data is written. - * This pointer can be NULL if len == 0. + * \param ctx The ChaCha20-Poly1305 context to use. + * \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. * - * \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned - * if \p ctx, \p input, or \p output are NULL. - * MBEDTLS_ERR_CHACHAPOLY_BAD_STATE is returned if - * the context has not been setup, or if the context has been - * finished. - * Otherwise, 0 is returned to indicate success. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CHACHAPOLY_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. */ int mbedtls_chachapoly_update( mbedtls_chachapoly_context *ctx, size_t len, @@ -179,42 +221,51 @@ int mbedtls_chachapoly_update( mbedtls_chachapoly_context *ctx, unsigned char *output ); /** - * \brief Compute the ChaCha20-Poly1305 MAC. + * \brief This function finished the ChaCha20-Poly1305 operation and + * generates the MAC (authentication tag). * - * \param ctx The ChaCha20-Poly1305 context. - * \param mac Buffer to where the 128-bit (16 bytes) MAC is written. + * \param ctx The ChaCha20-Poly1305 context to use. + * \param mac The buffer to where the 128-bit (16 bytes) MAC is written. * - * \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned - * if \p ctx or \p mac are NULL. - * MBEDTLS_ERR_CHACHAPOLY_BAD_STATE is returned if - * the context has not been setup. - * Otherwise, 0 is returned to indicate success. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CHACHAPOLY_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. */ int mbedtls_chachapoly_finish( mbedtls_chachapoly_context *ctx, unsigned char mac[16] ); /** - * \brief Encrypt or decrypt data, and produce a MAC (tag) with ChaCha20-Poly1305. + * \brief This function performs a complete ChaCha20-Poly1305 + * operation with the previously-set key. * - * \param ctx The ChachaPoly context. - * \param mode Specifies whether the data in the \p input buffer is to - * be encrypted or decrypted. If there is no data to encrypt - * or decrypt (i.e. \p ilen is 0) then the value of this - * parameter does not matter. - * \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 Buffer containing the additional authenticated data (AAD). - * This pointer can be NULL if aad_len == 0. - * \param aad_len The length (in bytes) of the AAD data to process. - * \param input Buffer containing the data to encrypt or decrypt. - * This pointer can be NULL if ilen == 0. - * \param output Buffer to where the encrypted or decrypted data is written. - * This pointer can be NULL if ilen == 0. - * \param tag Buffer to where the computed 128-bit (16 bytes) MAC is written. + * \note Before using this function, you must set the key with + * \c mbedtls_chachapoly_setkey(). * - * \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned - * if one or more of the required parameters are NULL. - * Otherwise, 0 is returned to indicate success. + * \warning You must never use the same nonce twice with the same key. + * This would void any confidentiality and authenticity + * guarantees for the messages encrypted with the same nonce + * and key. + * + * \param ctx The ChaCha20-Poly1305 context to use (holds the key). + * \param mode The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or + * #MBEDTLS_CHACHAPOLY_DECRYPT. + * \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. + * \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. + * \param output The buffer to where the encrypted or decrypted data is written. + * This pointer can be 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_CHACHAPOLY_BAD_INPUT_DATA + * if one or more of the required parameters are NULL. */ int mbedtls_chachapoly_crypt_and_tag( mbedtls_chachapoly_context *ctx, mbedtls_chachapoly_mode_t mode, @@ -227,22 +278,29 @@ int mbedtls_chachapoly_crypt_and_tag( mbedtls_chachapoly_context *ctx, unsigned char tag[16] ); /** - * \brief Decrypt data and check a MAC (tag) with ChaCha20-Poly1305. + * \brief This function performs a complete ChaCha20-Poly1305 + * authenticated decryption with the previously-set key. * - * \param ctx The ChachaPoly context. - * \param length The length of the input and output data. - * \param nonce The nonce / initialization vector. - * \param aad The buffer holding the additional authenticated data. - * \param aad_len The length of the additional authenticated data. - * \param tag The buffer holding the tag. - * \param input The buffer holding the input data. - * \param output The buffer for holding the output data. + * \note Before using this function, you must set the key with + * \c mbedtls_chachapoly_setkey(). * - * \return MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned - * if one or more of the required parameters are NULL. - * MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED if the tag does not - * match. - * Otherwise, 0 is returned to indicate success. + * \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 aad The buffer containing the additional authenticated data (AAD). + * This pointer can be 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. + * \param input The buffer containing the data to decrypt. + * This pointer can be NULL if ilen == 0. + * \param output The buffer to where the decrypted data is written. + * This pointer can be NULL if ilen == 0. + * + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CHACHAPOLY_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. */ int mbedtls_chachapoly_auth_decrypt( mbedtls_chachapoly_context *ctx, size_t length, @@ -254,9 +312,10 @@ int mbedtls_chachapoly_auth_decrypt( mbedtls_chachapoly_context *ctx, unsigned char *output ); /** - * \brief Checkup routine + * \brief The ChaCha20-Poly1305 checkup routine. * - * \return 0 if successful, or 1 if the test failed + * \return \c 0 on success. + * \return \c 1 on failure. */ int mbedtls_chachapoly_self_test( int verbose ); diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index ac1f564fb..591aa79aa 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -86,7 +86,7 @@ typedef enum { MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */ MBEDTLS_CIPHER_ID_BLOWFISH, /**< The Blowfish cipher. */ MBEDTLS_CIPHER_ID_ARC4, /**< The RC4 cipher. */ - MBEDTLS_CIPHER_ID_CHACHA20, /**< The Chacha20 cipher. */ + MBEDTLS_CIPHER_ID_CHACHA20, /**< The ChaCha20 cipher. */ } mbedtls_cipher_id_t; /** @@ -146,8 +146,8 @@ typedef enum { MBEDTLS_CIPHER_CAMELLIA_128_CCM, /**< Camellia cipher with 128-bit CCM mode. */ MBEDTLS_CIPHER_CAMELLIA_192_CCM, /**< Camellia cipher with 192-bit CCM mode. */ MBEDTLS_CIPHER_CAMELLIA_256_CCM, /**< Camellia cipher with 256-bit CCM mode. */ - MBEDTLS_CIPHER_CHACHA20, /**< Chacha20 stream cipher. */ - MBEDTLS_CIPHER_CHACHA20_POLY1305, /**< Chacha20-Poly1305 AEAD cipher. */ + MBEDTLS_CIPHER_CHACHA20, /**< ChaCha20 stream cipher. */ + MBEDTLS_CIPHER_CHACHA20_POLY1305, /**< ChaCha20-Poly1305 AEAD cipher. */ } mbedtls_cipher_type_t; /** Supported cipher modes. */ diff --git a/include/mbedtls/poly1305.h b/include/mbedtls/poly1305.h index f69191578..c2e2655e7 100644 --- a/include/mbedtls/poly1305.h +++ b/include/mbedtls/poly1305.h @@ -1,9 +1,18 @@ /** * \file poly1305.h * - * \brief Poly1305 authenticator algorithm. + * \brief This file containts Poly1305 definitions and functions. * - * Copyright (C) 2006-2016, ARM Limited, All Rights Reserved + * Poly1305 is a one-time message authenticator that can be used to + * authenticate messages. Poly1305-AES was created by Daniel + * Bernstein https://cr.yp.to/mac/poly1305-20050329.pdf The generic + * Poly1305 algorithm (not tied to AES) was also standardized in RFC + * 7539. + * + * \author Daniel King + */ + +/* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved. * SPDX-License-Identifier: Apache-2.0 * * Licensed under the Apache License, Version 2.0 (the "License"); you may @@ -18,8 +27,9 @@ * See the License for the specific language governing permissions and * limitations under the License. * - * This file is part of mbed TLS (https://tls.mbed.org) + * This file is part of Mbed TLS (https://tls.mbed.org) */ + #ifndef MBEDTLS_POLY1305_H #define MBEDTLS_POLY1305_H @@ -42,11 +52,11 @@ extern "C" { typedef struct { - uint32_t r[4]; /** Stores the value for 'r' (low 128 bits of the key) */ - uint32_t s[4]; /** Stores the value for 's' (high 128 bits of the key) */ - uint32_t acc[5]; /** Accumulator number */ - uint8_t queue[16]; /** Stores partial block data */ - size_t queue_len; /** Number of bytes stored in 'queue'. Always less than 16 */ + uint32_t r[4]; /** The value for 'r' (low 128 bits of the key). */ + uint32_t s[4]; /** The value for 's' (high 128 bits of the key). */ + uint32_t acc[5]; /** The accumulator number. */ + uint8_t queue[16]; /** The current partial block of data. */ + size_t queue_len; /** The number of bytes stored in 'queue'. */ } mbedtls_poly1305_context; @@ -55,82 +65,97 @@ mbedtls_poly1305_context; #endif /* MBEDTLS_POLY1305_ALT */ /** - * \brief Initialize a Poly1305 context + * \brief This function initializes the specified Poly1305 context. * - * \param ctx The Poly1305 context to be initialized + * It must be the first API called before using + * the context. + * + * It is usually followed by a call to + * \c mbedtls_poly1305_starts(), then one or more calls to + * \c mbedtls_poly1305_update(), then one call to + * \c mbedtls_poly1305_finish(), then finally + * \c mbedtls_poly1305_free(). + * + * \param ctx The Poly1305 context to initialize. */ void mbedtls_poly1305_init( mbedtls_poly1305_context *ctx ); /** - * \brief Clear a Poly1305 context + * \brief This function releases and clears the specified Poly1305 context. * - * \param ctx The Poly1305 context to be cleared + * \param ctx The Poly1305 context to clear. */ void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx ); /** - * \brief Set the Poly1305 authentication key. + * \brief This function sets the one-time authentication key. * - * \warning The key should be unique, and \b MUST be - * unpredictable for each invocation of Poly1305. + * \warning The key must be unique and unpredictable for each + * invocation of Poly1305. * - * \param ctx The Poly1305 context. - * \param key Buffer containing the 256-bit key. + * \param ctx The Poly1305 context to which the key should be bound. + * \param key The buffer containing the 256-bit key. * - * \return MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA is returned if ctx - * or key are NULL. - * Otherwise, 0 is returned to indicate success. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA + * if ctx or key are NULL. */ int mbedtls_poly1305_starts( mbedtls_poly1305_context *ctx, const unsigned char key[32] ); /** - * \brief Process data with Poly1305. + * \brief This functions feeds an input bufer into an ongoing + * Poly1305 computation. * - * This function can be called multiple times to process - * a stream of data. + * It is called between \c mbedtls_cipher_cmac_starts() and + * \c mbedtls_cipher_cmac_finish(). + * Can be called repeatedly to process a stream of data. * - * \param ctx The Poly1305 context. - * \param ilen The input length (in bytes). Any value is accepted. - * \param input Buffer containing the input data to Process. - * This pointer can be NULL if ilen == 0. + * \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. + * \param input The buffer holding the input data. + * This pointer can be NULL if ilen == 0. * - * \return MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA is returned if ctx - * or input are NULL. - * Otherwise, 0 is returned to indicate success. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA + * if ctx or input are NULL. */ int mbedtls_poly1305_update( mbedtls_poly1305_context *ctx, size_t ilen, const unsigned char *input ); /** - * \brief Generate the Poly1305 MAC. + * \brief This function generates the Poly1305 Message + * Authentication Code (MAC). * - * \param ctx The Poly1305 context. - * \param mac Buffer to where the MAC is written. Must be big enough - * to hold the 16-byte MAC. + * \param ctx The Poly1305 context to use for the Poly1305 operation. + * \param mac The buffer to where the MAC is written. Must be big enough + * to hold the 16-byte MAC. * - * \return MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA is returned if ctx - * or mac are NULL. - * Otherwise, 0 is returned to indicate success. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA + * if ctx or mac are NULL. */ int mbedtls_poly1305_finish( mbedtls_poly1305_context *ctx, unsigned char mac[16] ); /** - * \brief Generate the Poly1305 MAC of some data with the given key. + * \brief This function calculates the Poly1305 MAC of the input + * buffer with the provided key. * - * \warning The key should be unique, and \b MUST be - * unpredictable for each invocation of Poly1305. + * \warning The key must be unique and unpredictable for each + * invocation of Poly1305. * - * \param key Buffer containing the 256-bit (32 bytes) key. - * \param ilen The length of the input data (in bytes). - * \param input Buffer containing the input data to process. - * \param mac Buffer to where the 128-bit (16 bytes) MAC is written. + * \param key The buffer containing the 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. + * \param mac The buffer to where the MAC is written. Must be big enough + * to hold the 16-byte MAC. * - * \return MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA is returned if key, - * input, or mac are NULL. - * Otherwise, 0 is returned to indicate success. + * \return \c 0 on success. + * \return #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA + * if key, input, or mac are NULL. */ int mbedtls_poly1305_mac( const unsigned char key[32], size_t ilen, @@ -138,9 +163,10 @@ int mbedtls_poly1305_mac( const unsigned char key[32], unsigned char mac[16] ); /** - * \brief Checkup routine + * \brief The Poly1305 checkup routine. * - * \return 0 if successful, or 1 if the test failed + * \return \c 0 on success. + * \return \c 1 on failure. */ int mbedtls_poly1305_self_test( int verbose );