From 02f73a6b555c7784bd90ef25baecb4dbc3528c17 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 26 Mar 2018 18:02:32 +0100 Subject: [PATCH 1/7] Update cipher.h Minor documentation improvements: *Standardized file brief description. *Separated return statements. *Reordered tags within documentation blocks so that params and returns are last in block. *Added missing documentation in lines 99-159 (values in enums) - need to be verified. *lines 79+80 and 97+98 - verify descriptions + what is the difference here between none and null? *lines 177-187 - seems to be an enum without a name? --- include/mbedtls/cipher.h | 297 ++++++++++++++++++++------------------- 1 file changed, 156 insertions(+), 141 deletions(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index d1f4efef8..000d18fdc 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -1,7 +1,7 @@ /** * \file cipher.h * - * \brief The generic cipher wrapper. + * \brief Thif file contains the generic cipher wrapper. * * \author Adriaan de Jong */ @@ -69,93 +69,93 @@ extern "C" { #endif /** - * \brief An enumeration of supported ciphers. + * \brief Supported cipher types. * * \warning ARC4 and DES are considered weak ciphers and their use - * constitutes a security risk. We recommend considering stronger - * ciphers instead. + * constitutes a security risk. We recommend you consider using + * stronger ciphers instead. */ typedef enum { - MBEDTLS_CIPHER_ID_NONE = 0, - MBEDTLS_CIPHER_ID_NULL, - MBEDTLS_CIPHER_ID_AES, - MBEDTLS_CIPHER_ID_DES, - MBEDTLS_CIPHER_ID_3DES, - MBEDTLS_CIPHER_ID_CAMELLIA, - MBEDTLS_CIPHER_ID_BLOWFISH, - MBEDTLS_CIPHER_ID_ARC4, + MBEDTLS_CIPHER_ID_NONE = 0, /**< None. */ + MBEDTLS_CIPHER_ID_NULL, /**< NULL.*/ + MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */ + MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. */ + MBEDTLS_CIPHER_ID_3DES, /**< The 3DES cipher. */ + MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */ + MBEDTLS_CIPHER_ID_BLOWFISH, /**< The Blowfish cipher. */ + MBEDTLS_CIPHER_ID_ARC4, /**< The ARC4 cipher. */ } mbedtls_cipher_id_t; /** - * \brief An enumeration of supported (cipher, mode) pairs. + * \brief Supported {cipher type, cipher mode} pairs. * * \warning ARC4 and DES are considered weak ciphers and their use * constitutes a security risk. We recommend considering stronger * ciphers instead. */ typedef enum { - MBEDTLS_CIPHER_NONE = 0, - MBEDTLS_CIPHER_NULL, - MBEDTLS_CIPHER_AES_128_ECB, - MBEDTLS_CIPHER_AES_192_ECB, - MBEDTLS_CIPHER_AES_256_ECB, - MBEDTLS_CIPHER_AES_128_CBC, - MBEDTLS_CIPHER_AES_192_CBC, - MBEDTLS_CIPHER_AES_256_CBC, - MBEDTLS_CIPHER_AES_128_CFB128, - MBEDTLS_CIPHER_AES_192_CFB128, - MBEDTLS_CIPHER_AES_256_CFB128, - MBEDTLS_CIPHER_AES_128_CTR, - MBEDTLS_CIPHER_AES_192_CTR, - MBEDTLS_CIPHER_AES_256_CTR, - MBEDTLS_CIPHER_AES_128_GCM, - MBEDTLS_CIPHER_AES_192_GCM, - MBEDTLS_CIPHER_AES_256_GCM, - MBEDTLS_CIPHER_CAMELLIA_128_ECB, - MBEDTLS_CIPHER_CAMELLIA_192_ECB, - MBEDTLS_CIPHER_CAMELLIA_256_ECB, - MBEDTLS_CIPHER_CAMELLIA_128_CBC, - MBEDTLS_CIPHER_CAMELLIA_192_CBC, - MBEDTLS_CIPHER_CAMELLIA_256_CBC, - MBEDTLS_CIPHER_CAMELLIA_128_CFB128, - MBEDTLS_CIPHER_CAMELLIA_192_CFB128, - MBEDTLS_CIPHER_CAMELLIA_256_CFB128, - MBEDTLS_CIPHER_CAMELLIA_128_CTR, - MBEDTLS_CIPHER_CAMELLIA_192_CTR, - MBEDTLS_CIPHER_CAMELLIA_256_CTR, - MBEDTLS_CIPHER_CAMELLIA_128_GCM, - MBEDTLS_CIPHER_CAMELLIA_192_GCM, - MBEDTLS_CIPHER_CAMELLIA_256_GCM, - MBEDTLS_CIPHER_DES_ECB, - MBEDTLS_CIPHER_DES_CBC, - MBEDTLS_CIPHER_DES_EDE_ECB, - MBEDTLS_CIPHER_DES_EDE_CBC, - MBEDTLS_CIPHER_DES_EDE3_ECB, - MBEDTLS_CIPHER_DES_EDE3_CBC, - MBEDTLS_CIPHER_BLOWFISH_ECB, - MBEDTLS_CIPHER_BLOWFISH_CBC, - MBEDTLS_CIPHER_BLOWFISH_CFB64, - MBEDTLS_CIPHER_BLOWFISH_CTR, - MBEDTLS_CIPHER_ARC4_128, - MBEDTLS_CIPHER_AES_128_CCM, - MBEDTLS_CIPHER_AES_192_CCM, - MBEDTLS_CIPHER_AES_256_CCM, - MBEDTLS_CIPHER_CAMELLIA_128_CCM, - MBEDTLS_CIPHER_CAMELLIA_192_CCM, - MBEDTLS_CIPHER_CAMELLIA_256_CCM, + MBEDTLS_CIPHER_NONE = 0, /**< None. */ + MBEDTLS_CIPHER_NULL, /**< NULL. */ + MBEDTLS_CIPHER_AES_128_ECB, /**< AES cipher with 128-bit ECB mode. */ + MBEDTLS_CIPHER_AES_192_ECB, /**< AES cipher with 192-bit ECB mode. */ + MBEDTLS_CIPHER_AES_256_ECB, /**< AES cipher with 256-bit ECB mode. */ + MBEDTLS_CIPHER_AES_128_CBC, /**< AES cipher with 128-bit CBC mode. */ + MBEDTLS_CIPHER_AES_192_CBC, /**< AES cipher with 192-bit CBC mode. */ + MBEDTLS_CIPHER_AES_256_CBC, /**< AES cipher with 256-bit CBC mode. */ + MBEDTLS_CIPHER_AES_128_CFB128, /**< AES cipher with 128-bit CFB128 mode. */ + MBEDTLS_CIPHER_AES_192_CFB128, /**< AES cipher with 192-bit CFB128 mode. */ + MBEDTLS_CIPHER_AES_256_CFB128, /**< AES cipher with 256-bit CFB128 mode. */ + MBEDTLS_CIPHER_AES_128_CTR, /**< AES cipher with 128-bit CTR mode. */ + MBEDTLS_CIPHER_AES_192_CTR, /**< AES cipher with 192-bit CTR mode. */ + MBEDTLS_CIPHER_AES_256_CTR, /**< AES cipher with 256-bit CTR mode. */ + MBEDTLS_CIPHER_AES_128_GCM, /**< AES cipher with 128-bit GCM mode. */ + MBEDTLS_CIPHER_AES_192_GCM, /**< AES cipher with 192-bit GCM mode. */ + MBEDTLS_CIPHER_AES_256_GCM, /**< AES cipher with 256-bit GCM mode. */ + MBEDTLS_CIPHER_CAMELLIA_128_ECB, /**< Camellia cipher with 128-bit ECB mode. */ + MBEDTLS_CIPHER_CAMELLIA_192_ECB, /**< Camellia cipher with 192-bit ECB mode. */ + MBEDTLS_CIPHER_CAMELLIA_256_ECB, /**< Camellia cipher with 256-bit ECB mode. */ + MBEDTLS_CIPHER_CAMELLIA_128_CBC, /**< Camellia cipher with 128-bit CBC mode. */ + MBEDTLS_CIPHER_CAMELLIA_192_CBC, /**< Camellia cipher with 192-bit CBC mode. */ + MBEDTLS_CIPHER_CAMELLIA_256_CBC, /**< Camellia cipher with 256-bit CBC mode. */ + MBEDTLS_CIPHER_CAMELLIA_128_CFB128, /**< Camellia cipher with 128-bit CFB128 mode. */ + MBEDTLS_CIPHER_CAMELLIA_192_CFB128, /**< Camellia cipher with 192-bit CFB128 mode. */ + MBEDTLS_CIPHER_CAMELLIA_256_CFB128, /**< Camellia cipher with 256-bit CFB128 mode. */ + MBEDTLS_CIPHER_CAMELLIA_128_CTR, /**< Camellia cipher with 128-bit CTR mode. */ + MBEDTLS_CIPHER_CAMELLIA_192_CTR, /**< Camellia cipher with 192-bit CTR mode. */ + MBEDTLS_CIPHER_CAMELLIA_256_CTR, /**< Camellia cipher with 256-bit CTR mode. */ + MBEDTLS_CIPHER_CAMELLIA_128_GCM, /**< Camellia cipher with 128-bit GCM mode. */ + MBEDTLS_CIPHER_CAMELLIA_192_GCM, /**< Camellia cipher with 192-bit GCM mode. */ + MBEDTLS_CIPHER_CAMELLIA_256_GCM, /**< Camellia cipher with 256-bit GCM mode. */ + MBEDTLS_CIPHER_DES_ECB, /**< DES cipher with ECB mode. */ + MBEDTLS_CIPHER_DES_CBC, /**< DES cipher with CBC mode. */ + MBEDTLS_CIPHER_DES_EDE_ECB, /**< DES cipher with EDE ECB mode. */ + MBEDTLS_CIPHER_DES_EDE_CBC, /**< DES cipher with EDE CBC mode. */ + MBEDTLS_CIPHER_DES_EDE3_ECB, /**< DES cipher with EDE3 ECB mode. */ + MBEDTLS_CIPHER_DES_EDE3_CBC, /**< DES cipher with EDE3 CBC mode. */ + MBEDTLS_CIPHER_BLOWFISH_ECB, /**< Blowfish cipher with ECB mode. */ + MBEDTLS_CIPHER_BLOWFISH_CBC, /**< Blowfish cipher with CBC mode. */ + MBEDTLS_CIPHER_BLOWFISH_CFB64, /**< Blowfish cipher with CFB64 mode. */ + MBEDTLS_CIPHER_BLOWFISH_CTR, /**< Blowfish cipher with CTR mode. */ + MBEDTLS_CIPHER_ARC4_128, /**< ARC4 cipher with 128-bit mode. */ + MBEDTLS_CIPHER_AES_128_CCM, /**< AES cipher with 128-bit CCM mode. */ + MBEDTLS_CIPHER_AES_192_CCM, /**< AES cipher with 192-bit CCM mode. */ + MBEDTLS_CIPHER_AES_256_CCM, /**< AES cipher with 256-bit CCM mode. */ + 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_type_t; /** Supported cipher modes. */ typedef enum { - MBEDTLS_MODE_NONE = 0, - MBEDTLS_MODE_ECB, - MBEDTLS_MODE_CBC, - MBEDTLS_MODE_CFB, - MBEDTLS_MODE_OFB, /* Unused! */ - MBEDTLS_MODE_CTR, - MBEDTLS_MODE_GCM, - MBEDTLS_MODE_STREAM, - MBEDTLS_MODE_CCM, + MBEDTLS_MODE_NONE = 0, /**< None. */ + MBEDTLS_MODE_ECB, /**< The ECB cipher mode. */ + MBEDTLS_MODE_CBC, /**< The CBC cipher mode. */ + MBEDTLS_MODE_CFB, /**< The CFB cipher mode. */ + MBEDTLS_MODE_OFB, /**< Unused. */ + MBEDTLS_MODE_CTR, /**< The CTR cipher mode. */ + MBEDTLS_MODE_GCM, /**< The GCM cipher mode. */ + MBEDTLS_MODE_STREAM, /**< The stream cipher mode. */ + MBEDTLS_MODE_CCM, /**< The CCM cipher mode. */ } mbedtls_cipher_mode_t; /** Supported cipher padding types. */ @@ -163,8 +163,8 @@ typedef enum { MBEDTLS_PADDING_PKCS7 = 0, /**< PKCS7 padding (default). */ MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding. */ MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding. */ - MBEDTLS_PADDING_ZEROS, /**< zero padding (not reversible). */ - MBEDTLS_PADDING_NONE, /**< never pad (full blocks only). */ + MBEDTLS_PADDING_ZEROS, /**< Zero padding (not reversible). */ + MBEDTLS_PADDING_NONE, /**< Never pad (full blocks only). */ } mbedtls_cipher_padding_t; /** Type of operation. */ @@ -228,7 +228,8 @@ typedef struct { */ unsigned int iv_size; - /** Flags to set. For example, if the cipher supports variable IV sizes or variable key sizes. */ + /** Flags to set. For example, if the cipher + supports variable IV sizes or variable key sizes. */ int flags; /** The block size, in Bytes. */ @@ -299,7 +300,8 @@ const int *mbedtls_cipher_list( void ); * \param cipher_name Name of the cipher to search for. * * \return The cipher information structure associated with the - * given \p cipher_name, or NULL if not found. + * given \p cipher_name. + * \return NULL if the associated cipher information is not found. */ const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name ); @@ -325,7 +327,8 @@ const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type( const mbedtls_cipher * \param mode The cipher mode. For example, #MBEDTLS_MODE_CBC. * * \return The cipher information structure associated with the - * given \p cipher_id, or NULL if not found. + * given \p cipher_id. + * \return NULL if the associated cipher information is not found. */ const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values( const mbedtls_cipher_id_t cipher_id, int key_bitlen, @@ -352,9 +355,9 @@ void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx ); * \param ctx The context to initialize. May not be NULL. * \param cipher_info The cipher to use. * - * \return \c 0 on success, - * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure, - * #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the + * \return \c 0 on success. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure. + * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the * cipher-specific context failed. * * \internal Currently, the function also clears the structure. @@ -368,8 +371,8 @@ int mbedtls_cipher_setup( mbedtls_cipher_context_t *ctx, const mbedtls_cipher_in * * \param ctx The context of the cipher. Must be initialized. * - * \return The size of the blocks of the cipher, or zero if \p ctx - * has not been initialized. + * \return The size of the blocks of the cipher. + * \return 0 if \p ctx has not been initialized. */ static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_context_t *ctx ) { @@ -385,8 +388,8 @@ static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_c * * \param ctx The context of the cipher. Must be initialized. * - * \return The mode of operation, or #MBEDTLS_MODE_NONE if - * \p ctx has not been initialized. + * \return The mode of operation. + * \return #MBEDTLS_MODE_NONE if \p ctx has not been initialized. */ static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtls_cipher_context_t *ctx ) { @@ -402,9 +405,9 @@ static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtl * * \param ctx The context of the cipher. Must be initialized. * - * \return + * \return The recommended IV size, if no IV has been set. + * 0 for ciphers not using IV or nonce. + * \return The actual size, if an IV has been set. */ static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx ) { @@ -422,8 +425,8 @@ static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ct * * \param ctx The context of the cipher. Must be initialized. * - * \return The type of the cipher, or #MBEDTLS_CIPHER_NONE if - * \p ctx has not been initialized. + * \return The type of the cipher. + * \return #MBEDTLS_CIPHER_NONE if \p ctx has not been initialized. */ static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( const mbedtls_cipher_context_t *ctx ) { @@ -439,8 +442,8 @@ static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( const mbedtls_ciphe * * \param ctx The context of the cipher. Must be initialized. * - * \return The name of the cipher, or NULL if \p ctx has not - * been not initialized. + * \return The name of the cipher. + * \return NULL if \p ctx has not been not initialized. */ static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_t *ctx ) { @@ -455,8 +458,8 @@ static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_ * * \param ctx The context of the cipher. Must be initialized. * - * \return The key length of the cipher in bits, or - * #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been + * \return The key length of the cipher in bits. + * \return #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been * initialized. */ static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t *ctx ) @@ -473,7 +476,8 @@ static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t * \param ctx The context of the cipher. Must be initialized. * * \return The type of operation: #MBEDTLS_ENCRYPT or - * #MBEDTLS_DECRYPT, or #MBEDTLS_OPERATION_NONE if \p ctx + * #MBEDTLS_DECRYPT. + * \return #MBEDTLS_OPERATION_NONE if \p ctx * has not been initialized. */ static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_cipher_context_t *ctx ) @@ -495,9 +499,10 @@ static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_ci * \param operation The operation that the key will be used for: * #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT. * - * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if - * parameter verification fails, or a cipher-specific - * error code. + * \returns \c 0 on success. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if + * parameter verification fails. + * \return A cipher-specific error code. */ int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key, int key_bitlen, const mbedtls_operation_t operation ); @@ -512,9 +517,10 @@ int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *k * \param ctx The generic cipher context. * \param mode The padding mode. * - * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE - * if the selected padding mode is not supported, or - * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode + * \returns \c 0 on success. + * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE + * if the selected padding mode is not supported. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode * does not support padding. */ int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_cipher_padding_t mode ); @@ -524,15 +530,16 @@ int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_ciph * \brief This function sets the initialization vector (IV) * or nonce. * + * \note Some ciphers do not use IVs nor nonce. For these + * ciphers, this function has no effect. + * * \param ctx The generic cipher context. * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. * \param iv_len The IV length for ciphers with variable-size IV. * This parameter is discarded by ciphers with fixed-size IV. * - * \returns \c 0 on success, or #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA - * - * \note Some ciphers do not use IVs nor nonce. For these - * ciphers, this function has no effect. + * \returns \c 0 on success. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on failure. */ int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len ); @@ -542,7 +549,8 @@ int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx, * * \param ctx The generic cipher context. * - * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA + * \returns \c 0 on success. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA * if parameter verification fails. */ int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx ); @@ -557,7 +565,8 @@ int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx ); * \param ad The additional data to use. * \param ad_len the Length of \p ad. * - * \return \c 0 on success, or a specific error code on failure. + * \return \c 0 on success. + * \return A specific error code on failure. */ int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx, const unsigned char *ad, size_t ad_len ); @@ -573,6 +582,11 @@ int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx, * Exception: For MBEDTLS_MODE_ECB, expects a single block * in size. For example, 16 Bytes for AES. * + * \note If the underlying cipher is GCM, all calls to this + * function, except the last one before + * mbedtls_cipher_finish(). Must have \p ilen as a + * multiple of the block_size. + * * \param ctx The generic cipher context. * \param input The buffer holding the input data. * \param ilen The length of the input data. @@ -582,16 +596,12 @@ int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx, * \param olen The length of the output data, to be updated with the * actual number of Bytes written. * - * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if - * parameter verification fails, - * #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an - * unsupported mode for a cipher, or a cipher-specific - * error code. - * - * \note If the underlying cipher is GCM, all calls to this - * function, except the last one before - * mbedtls_cipher_finish(). Must have \p ilen as a - * multiple of the block_size. + * \returns \c 0 on success. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if + * parameter verification fails. + * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an + * unsupported mode for a cipher. + * \return A cipher-specific error code. */ int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen ); @@ -606,13 +616,15 @@ int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *i * \param output The buffer to write data to. Needs block_size available. * \param olen The length of the data written to the \p output buffer. * - * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if - * parameter verification fails, - * #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption - * expected a full block but was not provided one, - * #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding - * while decrypting, or a cipher-specific error code - * on failure for any other reason. + * \returns \c 0 on success. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if + * parameter verification fails. + * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption + * expected a full block but was not provided one. + * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding + * while decrypting. + * \return A cipher-specific error code on failure for any other + * reason. */ int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx, unsigned char *output, size_t *olen ); @@ -627,7 +639,8 @@ int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx, * \param tag The buffer to write the tag to. * \param tag_len The length of the tag to write. * - * \return \c 0 on success, or a specific error code on failure. + * \return \c 0 on success. + * \return A specific error code on failure. */ int mbedtls_cipher_write_tag( mbedtls_cipher_context_t *ctx, unsigned char *tag, size_t tag_len ); @@ -641,7 +654,8 @@ int mbedtls_cipher_write_tag( mbedtls_cipher_context_t *ctx, * \param tag The buffer holding the tag. * \param tag_len The length of the tag to check. * - * \return \c 0 on success, or a specific error code on failure. + * \return \c 0 on success. + * \return A specific error code on failure. */ int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx, const unsigned char *tag, size_t tag_len ); @@ -667,13 +681,14 @@ int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx, * \note Some ciphers do not use IVs nor nonce. For these * ciphers, use \p iv = NULL and \p iv_len = 0. * - * \returns \c 0 on success, or - * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or + * \returns \c 0 on success. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or * #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption - * expected a full block but was not provided one, or - * #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding - * while decrypting, or a cipher-specific error code on - * failure for any other reason. + * expected a full block but was not provided one. + * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding + * while decrypting. + * \return A cipher-specific error code on failure for any other + * reason. */ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, @@ -699,9 +714,9 @@ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx, * \param tag The buffer for the authentication tag. * \param tag_len The desired length of the authentication tag. * - * \returns \c 0 on success, or - * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or - * a cipher-specific error code. + * \returns \c 0 on success. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA. + * \return A cipher-specific error code. */ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, @@ -713,6 +728,10 @@ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, /** * \brief The generic autenticated decryption (AEAD) function. * + * \note If the data is not authentic, then the output buffer + * is zeroed out to prevent the unauthentic plaintext being + * used, making this interface safer. + * * \param ctx The generic cipher context. * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. * \param iv_len The IV length for ciphers with variable-size IV. @@ -728,14 +747,10 @@ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, * \param tag The buffer holding the authentication tag. * \param tag_len The length of the authentication tag. * - * \returns \c 0 on success, or - * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or - * #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic, - * or a cipher-specific error code on failure for any other reason. - * - * \note If the data is not authentic, then the output buffer - * is zeroed out to prevent the unauthentic plaintext being - * used, making this interface safer. + * \returns \c 0 on success. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA. + * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic. + * \return A cipher-specific error code on failure for any other reason. */ int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, From 02facfb4d9a176f68bdaf8251160e52bf85a8258 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Tue, 27 Mar 2018 10:26:56 +0100 Subject: [PATCH 2/7] Update cipher.h --- include/mbedtls/cipher.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 000d18fdc..216771517 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -1,7 +1,7 @@ /** * \file cipher.h * - * \brief Thif file contains the generic cipher wrapper. + * \brief This file contains the generic cipher wrapper. * * \author Adriaan de Jong */ From b5607bf61d80d08520dd557e2041599940d2f077 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Mon, 16 Apr 2018 10:34:51 +0100 Subject: [PATCH 3/7] Update cipher.h minor changes based on comments --- include/mbedtls/cipher.h | 59 ++++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 30 deletions(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 216771517..3ecae9b06 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -72,8 +72,8 @@ extern "C" { * \brief Supported cipher types. * * \warning ARC4 and DES are considered weak ciphers and their use - * constitutes a security risk. We recommend you consider using - * stronger ciphers instead. + * constitutes a security risk. Arm recommends considering stronger + * ciphers instead. */ typedef enum { MBEDTLS_CIPHER_ID_NONE = 0, /**< None. */ @@ -90,7 +90,7 @@ typedef enum { * \brief Supported {cipher type, cipher mode} pairs. * * \warning ARC4 and DES are considered weak ciphers and their use - * constitutes a security risk. We recommend considering stronger + * constitutes a security risk. Arm recommends considering stronger * ciphers instead. */ typedef enum { @@ -228,8 +228,10 @@ typedef struct { */ unsigned int iv_size; - /** Flags to set. For example, if the cipher - supports variable IV sizes or variable key sizes. */ + /** Bitflag comprised of MBEDTLS_CIPHER_VARIABLE_IV_LEN and + * MBEDTLS_CIPHER_VARIABLE_KEY_LEN indicating whether the + * cipher supports variable IV or variable key sizes, respectively. + */ int flags; /** The block size, in Bytes. */ @@ -312,7 +314,8 @@ const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher * \param cipher_type Type of the cipher to search for. * * \return The cipher information structure associated with the - * given \p cipher_type, or NULL if not found. + * given \p cipher_type. + * \return NULL if the associated cipher information is not found. */ const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type( const mbedtls_cipher_type_t cipher_type ); @@ -405,9 +408,9 @@ static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtl * * \param ctx The context of the cipher. Must be initialized. * - * \return The recommended IV size, if no IV has been set. - * 0 for ciphers not using IV or nonce. - * \return The actual size, if an IV has been set. + * \return The recommended IV size if no IV has been set. + * \return 0 for ciphers not using IV or nonce. + * \return The actual size if an IV has been set. */ static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx ) { @@ -475,10 +478,8 @@ static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t * * \param ctx The context of the cipher. Must be initialized. * - * \return The type of operation: #MBEDTLS_ENCRYPT or - * #MBEDTLS_DECRYPT. - * \return #MBEDTLS_OPERATION_NONE if \p ctx - * has not been initialized. + * \return The type of operation: #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT. + * \return #MBEDTLS_OPERATION_NONE if \p ctx has not been initialized. */ static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_cipher_context_t *ctx ) { @@ -499,10 +500,10 @@ static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_ci * \param operation The operation that the key will be used for: * #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if * parameter verification fails. - * \return A cipher-specific error code. + * \return A cipher-specific error code on failure. */ int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key, int key_bitlen, const mbedtls_operation_t operation ); @@ -517,7 +518,7 @@ int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *k * \param ctx The generic cipher context. * \param mode The padding mode. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE * if the selected padding mode is not supported. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode @@ -538,7 +539,7 @@ int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_ciph * \param iv_len The IV length for ciphers with variable-size IV. * This parameter is discarded by ciphers with fixed-size IV. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on failure. */ int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx, @@ -549,7 +550,7 @@ int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx, * * \param ctx The generic cipher context. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA * if parameter verification fails. */ @@ -596,12 +597,12 @@ int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx, * \param olen The length of the output data, to be updated with the * actual number of Bytes written. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if * parameter verification fails. * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an * unsupported mode for a cipher. - * \return A cipher-specific error code. + * \return A cipher-specific error code on failure. */ int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen ); @@ -616,15 +617,14 @@ int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *i * \param output The buffer to write data to. Needs block_size available. * \param olen The length of the data written to the \p output buffer. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if * parameter verification fails. * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption * expected a full block but was not provided one. * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * while decrypting. - * \return A cipher-specific error code on failure for any other - * reason. + * \return A cipher-specific error code on failure. */ int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx, unsigned char *output, size_t *olen ); @@ -681,14 +681,13 @@ int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx, * \note Some ciphers do not use IVs nor nonce. For these * ciphers, use \p iv = NULL and \p iv_len = 0. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or * #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption * expected a full block but was not provided one. * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * while decrypting. - * \return A cipher-specific error code on failure for any other - * reason. + * \return A cipher-specific error code on failure. */ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, @@ -714,9 +713,9 @@ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx, * \param tag The buffer for the authentication tag. * \param tag_len The desired length of the authentication tag. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA. - * \return A cipher-specific error code. + * \return A cipher-specific error code on failure. */ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, @@ -747,10 +746,10 @@ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, * \param tag The buffer holding the authentication tag. * \param tag_len The length of the authentication tag. * - * \returns \c 0 on success. + * \return \c 0 on success. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA. * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic. - * \return A cipher-specific error code on failure for any other reason. + * \return A cipher-specific error code on failure. */ int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, From 826f26492008095bfe919784d4c6ae867240f3c8 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Thu, 19 Apr 2018 14:01:29 +0100 Subject: [PATCH 4/7] Update cipher.h Additional changes based on review comments --- include/mbedtls/cipher.h | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 3ecae9b06..416942846 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -1,7 +1,9 @@ /** * \file cipher.h * - * \brief This file contains the generic cipher wrapper. + * \brief This file contains an abstraction interface for use with the cipher + * primitives provided by the library. It provides a common interface to all of + * the available cipher operations. * * \author Adriaan de Jong */ @@ -71,7 +73,7 @@ extern "C" { /** * \brief Supported cipher types. * - * \warning ARC4 and DES are considered weak ciphers and their use + * \warning RC4 and DES are considered weak ciphers and their use * constitutes a security risk. Arm recommends considering stronger * ciphers instead. */ @@ -80,16 +82,16 @@ typedef enum { MBEDTLS_CIPHER_ID_NULL, /**< NULL.*/ MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */ MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. */ - MBEDTLS_CIPHER_ID_3DES, /**< The 3DES cipher. */ + MBEDTLS_CIPHER_ID_3DES, /**< The Trile DES cipher. */ MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */ MBEDTLS_CIPHER_ID_BLOWFISH, /**< The Blowfish cipher. */ - MBEDTLS_CIPHER_ID_ARC4, /**< The ARC4 cipher. */ + MBEDTLS_CIPHER_ID_ARC4, /**< The RC4 cipher. */ } mbedtls_cipher_id_t; /** * \brief Supported {cipher type, cipher mode} pairs. * - * \warning ARC4 and DES are considered weak ciphers and their use + * \warning RC4 and DES are considered weak ciphers and their use * constitutes a security risk. Arm recommends considering stronger * ciphers instead. */ @@ -136,7 +138,7 @@ typedef enum { MBEDTLS_CIPHER_BLOWFISH_CBC, /**< Blowfish cipher with CBC mode. */ MBEDTLS_CIPHER_BLOWFISH_CFB64, /**< Blowfish cipher with CFB64 mode. */ MBEDTLS_CIPHER_BLOWFISH_CTR, /**< Blowfish cipher with CTR mode. */ - MBEDTLS_CIPHER_ARC4_128, /**< ARC4 cipher with 128-bit mode. */ + MBEDTLS_CIPHER_ARC4_128, /**< RC4 cipher with 128-bit mode. */ MBEDTLS_CIPHER_AES_128_CCM, /**< AES cipher with 128-bit CCM mode. */ MBEDTLS_CIPHER_AES_192_CCM, /**< AES cipher with 192-bit CCM mode. */ MBEDTLS_CIPHER_AES_256_CCM, /**< AES cipher with 256-bit CCM mode. */ @@ -151,7 +153,7 @@ typedef enum { MBEDTLS_MODE_ECB, /**< The ECB cipher mode. */ MBEDTLS_MODE_CBC, /**< The CBC cipher mode. */ MBEDTLS_MODE_CFB, /**< The CFB cipher mode. */ - MBEDTLS_MODE_OFB, /**< Unused. */ + MBEDTLS_MODE_OFB, /**< The OFB cipher mode - unsupported. */ MBEDTLS_MODE_CTR, /**< The CTR cipher mode. */ MBEDTLS_MODE_GCM, /**< The GCM cipher mode. */ MBEDTLS_MODE_STREAM, /**< The stream cipher mode. */ @@ -409,7 +411,7 @@ static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtl * \param ctx The context of the cipher. Must be initialized. * * \return The recommended IV size if no IV has been set. - * \return 0 for ciphers not using IV or nonce. + * \return \c 0 for ciphers not using IV or nonce. * \return The actual size if an IV has been set. */ static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx ) From 4c368e82cc5456303d4f0d0b7e5fd25c6a240b1a Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Thu, 19 Apr 2018 14:24:11 +0100 Subject: [PATCH 5/7] Update cipher.h Additional changes based on review comments --- include/mbedtls/cipher.h | 59 ++++++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 27 deletions(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 416942846..473181762 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -78,8 +78,8 @@ extern "C" { * ciphers instead. */ typedef enum { - MBEDTLS_CIPHER_ID_NONE = 0, /**< None. */ - MBEDTLS_CIPHER_ID_NULL, /**< NULL.*/ + MBEDTLS_CIPHER_ID_NONE = 0, /**< Placeholder to mark the end of cipher ID lists. */ + MBEDTLS_CIPHER_ID_NULL, /**< The identity cipher, treated as a stream cipher. */ MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */ MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. */ MBEDTLS_CIPHER_ID_3DES, /**< The Trile DES cipher. */ @@ -96,8 +96,8 @@ typedef enum { * ciphers instead. */ typedef enum { - MBEDTLS_CIPHER_NONE = 0, /**< None. */ - MBEDTLS_CIPHER_NULL, /**< NULL. */ + MBEDTLS_CIPHER_NONE = 0, /**< Placeholder to mark the end of cipher-pair lists. */ + MBEDTLS_CIPHER_NULL, /**< The cipher-pair, treated as a stream cipher. */ MBEDTLS_CIPHER_AES_128_ECB, /**< AES cipher with 128-bit ECB mode. */ MBEDTLS_CIPHER_AES_192_ECB, /**< AES cipher with 192-bit ECB mode. */ MBEDTLS_CIPHER_AES_256_ECB, /**< AES cipher with 256-bit ECB mode. */ @@ -361,9 +361,10 @@ void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx ); * \param cipher_info The cipher to use. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the - * cipher-specific context failed. + * cipher-specific context fails. * * \internal Currently, the function also clears the structure. * In future versions, the caller will be required to call @@ -411,7 +412,7 @@ static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtl * \param ctx The context of the cipher. Must be initialized. * * \return The recommended IV size if no IV has been set. - * \return \c 0 for ciphers not using IV or nonce. + * \return \c 0 for ciphers not using an IV or a nonce. * \return The actual size if an IV has been set. */ static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx ) @@ -503,8 +504,8 @@ static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_ci * #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if - * parameter verification fails. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. * \return A cipher-specific error code on failure. */ int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key, @@ -542,7 +543,8 @@ int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_ciph * This parameter is discarded by ciphers with fixed-size IV. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on failure. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. */ int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len ); @@ -553,8 +555,8 @@ int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx, * \param ctx The generic cipher context. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA - * if parameter verification fails. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. */ int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx ); @@ -585,10 +587,10 @@ int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx, * Exception: For MBEDTLS_MODE_ECB, expects a single block * in size. For example, 16 Bytes for AES. * - * \note If the underlying cipher is GCM, all calls to this - * function, except the last one before - * mbedtls_cipher_finish(). Must have \p ilen as a - * multiple of the block_size. + * \note If the underlying cipher is used in GCM mode, all calls + * to this function, except for the last one before + * mbedtls_cipher_finish(), must have \p ilen as a + * multiple of the block size of the cipher. * * \param ctx The generic cipher context. * \param input The buffer holding the input data. @@ -600,8 +602,8 @@ int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx, * actual number of Bytes written. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if - * parameter verification fails. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an * unsupported mode for a cipher. * \return A cipher-specific error code on failure. @@ -620,10 +622,10 @@ int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *i * \param olen The length of the data written to the \p output buffer. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if - * parameter verification fails. - * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption - * expected a full block but was not provided one. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. + * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption + * expecting a full block but not receiving one. * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * while decrypting. * \return A cipher-specific error code on failure. @@ -684,9 +686,10 @@ int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx, * ciphers, use \p iv = NULL and \p iv_len = 0. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or - * #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption - * expected a full block but was not provided one. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. + * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption + * expecting a full block but not receiving one. * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * while decrypting. * \return A cipher-specific error code on failure. @@ -716,7 +719,8 @@ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx, * \param tag_len The desired length of the authentication tag. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. * \return A cipher-specific error code on failure. */ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, @@ -749,7 +753,8 @@ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, * \param tag_len The length of the authentication tag. * * \return \c 0 on success. - * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA. + * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on + * parameter-verification failure. * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic. * \return A cipher-specific error code on failure. */ From c441f7490005800065b206dbfaabbabfe54b9fe7 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Thu, 19 Apr 2018 14:38:20 +0100 Subject: [PATCH 6/7] Update cipher.h minor fix --- include/mbedtls/cipher.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 473181762..a13145208 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -97,7 +97,7 @@ typedef enum { */ typedef enum { MBEDTLS_CIPHER_NONE = 0, /**< Placeholder to mark the end of cipher-pair lists. */ - MBEDTLS_CIPHER_NULL, /**< The cipher-pair, treated as a stream cipher. */ + MBEDTLS_CIPHER_NULL, /**< The identity stream cipher. */ MBEDTLS_CIPHER_AES_128_ECB, /**< AES cipher with 128-bit ECB mode. */ MBEDTLS_CIPHER_AES_192_ECB, /**< AES cipher with 192-bit ECB mode. */ MBEDTLS_CIPHER_AES_256_ECB, /**< AES cipher with 256-bit ECB mode. */ From 93f9919c26d8a42bc3ead452964b8e5b189b0522 Mon Sep 17 00:00:00 2001 From: Rose Zadik Date: Thu, 19 Apr 2018 14:41:33 +0100 Subject: [PATCH 7/7] Update cipher.h Fixed typo. --- include/mbedtls/cipher.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index a13145208..3ee2ab7db 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -82,7 +82,7 @@ typedef enum { MBEDTLS_CIPHER_ID_NULL, /**< The identity cipher, treated as a stream cipher. */ MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */ MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. */ - MBEDTLS_CIPHER_ID_3DES, /**< The Trile DES cipher. */ + MBEDTLS_CIPHER_ID_3DES, /**< The Triple DES cipher. */ MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */ MBEDTLS_CIPHER_ID_BLOWFISH, /**< The Blowfish cipher. */ MBEDTLS_CIPHER_ID_ARC4, /**< The RC4 cipher. */