yuzu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-10-18 22:01:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update cipher.h

Browse source 
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?
This commit is contained in:
Rose Zadik 2018-03-26 18:02:32 +01:00 committed by GitHub
parent f65379bc40
commit 02f73a6b55
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 156 additions and 141 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

297
include/mbedtls/cipher.h
View file

@ -1,7 +1,7 @@
/** /**
* \file cipher.h * \file cipher.h
* *
* \brief The generic cipher wrapper. * \brief Thif file contains the generic cipher wrapper.
* *
* \author Adriaan de Jong <dejong@fox-it.com> * \author Adriaan de Jong <dejong@fox-it.com>
*/ */
@ -69,93 +69,93 @@ extern "C" {
#endif #endif
/** /**
* \brief An enumeration of supported ciphers. * \brief Supported cipher types.
* *
* \warning ARC4 and DES are considered weak ciphers and their use * \warning ARC4 and DES are considered weak ciphers and their use
* constitutes a security risk. We recommend considering stronger * constitutes a security risk. We recommend you consider using
* ciphers instead. * stronger ciphers instead.
*/ */
typedef enum { typedef enum {
MBEDTLS_CIPHER_ID_NONE = 0, MBEDTLS_CIPHER_ID_NONE = 0, /**< None. */
MBEDTLS_CIPHER_ID_NULL, MBEDTLS_CIPHER_ID_NULL, /**< NULL.*/
MBEDTLS_CIPHER_ID_AES, MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */
MBEDTLS_CIPHER_ID_DES, MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. */
MBEDTLS_CIPHER_ID_3DES, MBEDTLS_CIPHER_ID_3DES, /**< The 3DES cipher. */
MBEDTLS_CIPHER_ID_CAMELLIA, MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */
MBEDTLS_CIPHER_ID_BLOWFISH, MBEDTLS_CIPHER_ID_BLOWFISH, /**< The Blowfish cipher. */
MBEDTLS_CIPHER_ID_ARC4, MBEDTLS_CIPHER_ID_ARC4, /**< The ARC4 cipher. */
} mbedtls_cipher_id_t; } 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 * \warning ARC4 and DES are considered weak ciphers and their use
* constitutes a security risk. We recommend considering stronger * constitutes a security risk. We recommend considering stronger
* ciphers instead. * ciphers instead.
*/ */
typedef enum { typedef enum {
MBEDTLS_CIPHER_NONE = 0, MBEDTLS_CIPHER_NONE = 0, /**< None. */
MBEDTLS_CIPHER_NULL, MBEDTLS_CIPHER_NULL, /**< NULL. */
MBEDTLS_CIPHER_AES_128_ECB, MBEDTLS_CIPHER_AES_128_ECB, /**< AES cipher with 128-bit ECB mode. */
MBEDTLS_CIPHER_AES_192_ECB, MBEDTLS_CIPHER_AES_192_ECB, /**< AES cipher with 192-bit ECB mode. */
MBEDTLS_CIPHER_AES_256_ECB, MBEDTLS_CIPHER_AES_256_ECB, /**< AES cipher with 256-bit ECB mode. */
MBEDTLS_CIPHER_AES_128_CBC, MBEDTLS_CIPHER_AES_128_CBC, /**< AES cipher with 128-bit CBC mode. */
MBEDTLS_CIPHER_AES_192_CBC, MBEDTLS_CIPHER_AES_192_CBC, /**< AES cipher with 192-bit CBC mode. */
MBEDTLS_CIPHER_AES_256_CBC, MBEDTLS_CIPHER_AES_256_CBC, /**< AES cipher with 256-bit CBC mode. */
MBEDTLS_CIPHER_AES_128_CFB128, MBEDTLS_CIPHER_AES_128_CFB128, /**< AES cipher with 128-bit CFB128 mode. */
MBEDTLS_CIPHER_AES_192_CFB128, MBEDTLS_CIPHER_AES_192_CFB128, /**< AES cipher with 192-bit CFB128 mode. */
MBEDTLS_CIPHER_AES_256_CFB128, MBEDTLS_CIPHER_AES_256_CFB128, /**< AES cipher with 256-bit CFB128 mode. */
MBEDTLS_CIPHER_AES_128_CTR, MBEDTLS_CIPHER_AES_128_CTR, /**< AES cipher with 128-bit CTR mode. */
MBEDTLS_CIPHER_AES_192_CTR, MBEDTLS_CIPHER_AES_192_CTR, /**< AES cipher with 192-bit CTR mode. */
MBEDTLS_CIPHER_AES_256_CTR, MBEDTLS_CIPHER_AES_256_CTR, /**< AES cipher with 256-bit CTR mode. */
MBEDTLS_CIPHER_AES_128_GCM, MBEDTLS_CIPHER_AES_128_GCM, /**< AES cipher with 128-bit GCM mode. */
MBEDTLS_CIPHER_AES_192_GCM, MBEDTLS_CIPHER_AES_192_GCM, /**< AES cipher with 192-bit GCM mode. */
MBEDTLS_CIPHER_AES_256_GCM, MBEDTLS_CIPHER_AES_256_GCM, /**< AES cipher with 256-bit GCM mode. */
MBEDTLS_CIPHER_CAMELLIA_128_ECB, MBEDTLS_CIPHER_CAMELLIA_128_ECB, /**< Camellia cipher with 128-bit ECB mode. */
MBEDTLS_CIPHER_CAMELLIA_192_ECB, MBEDTLS_CIPHER_CAMELLIA_192_ECB, /**< Camellia cipher with 192-bit ECB mode. */
MBEDTLS_CIPHER_CAMELLIA_256_ECB, MBEDTLS_CIPHER_CAMELLIA_256_ECB, /**< Camellia cipher with 256-bit ECB mode. */
MBEDTLS_CIPHER_CAMELLIA_128_CBC, MBEDTLS_CIPHER_CAMELLIA_128_CBC, /**< Camellia cipher with 128-bit CBC mode. */
MBEDTLS_CIPHER_CAMELLIA_192_CBC, MBEDTLS_CIPHER_CAMELLIA_192_CBC, /**< Camellia cipher with 192-bit CBC mode. */
MBEDTLS_CIPHER_CAMELLIA_256_CBC, MBEDTLS_CIPHER_CAMELLIA_256_CBC, /**< Camellia cipher with 256-bit CBC mode. */
MBEDTLS_CIPHER_CAMELLIA_128_CFB128, MBEDTLS_CIPHER_CAMELLIA_128_CFB128, /**< Camellia cipher with 128-bit CFB128 mode. */
MBEDTLS_CIPHER_CAMELLIA_192_CFB128, MBEDTLS_CIPHER_CAMELLIA_192_CFB128, /**< Camellia cipher with 192-bit CFB128 mode. */
MBEDTLS_CIPHER_CAMELLIA_256_CFB128, MBEDTLS_CIPHER_CAMELLIA_256_CFB128, /**< Camellia cipher with 256-bit CFB128 mode. */
MBEDTLS_CIPHER_CAMELLIA_128_CTR, MBEDTLS_CIPHER_CAMELLIA_128_CTR, /**< Camellia cipher with 128-bit CTR mode. */
MBEDTLS_CIPHER_CAMELLIA_192_CTR, MBEDTLS_CIPHER_CAMELLIA_192_CTR, /**< Camellia cipher with 192-bit CTR mode. */
MBEDTLS_CIPHER_CAMELLIA_256_CTR, MBEDTLS_CIPHER_CAMELLIA_256_CTR, /**< Camellia cipher with 256-bit CTR mode. */
MBEDTLS_CIPHER_CAMELLIA_128_GCM, MBEDTLS_CIPHER_CAMELLIA_128_GCM, /**< Camellia cipher with 128-bit GCM mode. */
MBEDTLS_CIPHER_CAMELLIA_192_GCM, MBEDTLS_CIPHER_CAMELLIA_192_GCM, /**< Camellia cipher with 192-bit GCM mode. */
MBEDTLS_CIPHER_CAMELLIA_256_GCM, MBEDTLS_CIPHER_CAMELLIA_256_GCM, /**< Camellia cipher with 256-bit GCM mode. */
MBEDTLS_CIPHER_DES_ECB, MBEDTLS_CIPHER_DES_ECB, /**< DES cipher with ECB mode. */
MBEDTLS_CIPHER_DES_CBC, MBEDTLS_CIPHER_DES_CBC, /**< DES cipher with CBC mode. */
MBEDTLS_CIPHER_DES_EDE_ECB, MBEDTLS_CIPHER_DES_EDE_ECB, /**< DES cipher with EDE ECB mode. */
MBEDTLS_CIPHER_DES_EDE_CBC, MBEDTLS_CIPHER_DES_EDE_CBC, /**< DES cipher with EDE CBC mode. */
MBEDTLS_CIPHER_DES_EDE3_ECB, MBEDTLS_CIPHER_DES_EDE3_ECB, /**< DES cipher with EDE3 ECB mode. */
MBEDTLS_CIPHER_DES_EDE3_CBC, MBEDTLS_CIPHER_DES_EDE3_CBC, /**< DES cipher with EDE3 CBC mode. */
MBEDTLS_CIPHER_BLOWFISH_ECB, MBEDTLS_CIPHER_BLOWFISH_ECB, /**< Blowfish cipher with ECB mode. */
MBEDTLS_CIPHER_BLOWFISH_CBC, MBEDTLS_CIPHER_BLOWFISH_CBC, /**< Blowfish cipher with CBC mode. */
MBEDTLS_CIPHER_BLOWFISH_CFB64, MBEDTLS_CIPHER_BLOWFISH_CFB64, /**< Blowfish cipher with CFB64 mode. */
MBEDTLS_CIPHER_BLOWFISH_CTR, MBEDTLS_CIPHER_BLOWFISH_CTR, /**< Blowfish cipher with CTR mode. */
MBEDTLS_CIPHER_ARC4_128, MBEDTLS_CIPHER_ARC4_128, /**< ARC4 cipher with 128-bit mode. */
MBEDTLS_CIPHER_AES_128_CCM, MBEDTLS_CIPHER_AES_128_CCM, /**< AES cipher with 128-bit CCM mode. */
MBEDTLS_CIPHER_AES_192_CCM, MBEDTLS_CIPHER_AES_192_CCM, /**< AES cipher with 192-bit CCM mode. */
MBEDTLS_CIPHER_AES_256_CCM, MBEDTLS_CIPHER_AES_256_CCM, /**< AES cipher with 256-bit CCM mode. */
MBEDTLS_CIPHER_CAMELLIA_128_CCM, MBEDTLS_CIPHER_CAMELLIA_128_CCM, /**< Camellia cipher with 128-bit CCM mode. */
MBEDTLS_CIPHER_CAMELLIA_192_CCM, MBEDTLS_CIPHER_CAMELLIA_192_CCM, /**< Camellia cipher with 192-bit CCM mode. */
MBEDTLS_CIPHER_CAMELLIA_256_CCM, MBEDTLS_CIPHER_CAMELLIA_256_CCM, /**< Camellia cipher with 256-bit CCM mode. */
} mbedtls_cipher_type_t; } mbedtls_cipher_type_t;
/** Supported cipher modes. */ /** Supported cipher modes. */
typedef enum { typedef enum {
MBEDTLS_MODE_NONE = 0, MBEDTLS_MODE_NONE = 0, /**< None. */
MBEDTLS_MODE_ECB, MBEDTLS_MODE_ECB, /**< The ECB cipher mode. */
MBEDTLS_MODE_CBC, MBEDTLS_MODE_CBC, /**< The CBC cipher mode. */
MBEDTLS_MODE_CFB, MBEDTLS_MODE_CFB, /**< The CFB cipher mode. */
MBEDTLS_MODE_OFB, /* Unused! */ MBEDTLS_MODE_OFB, /**< Unused. */
MBEDTLS_MODE_CTR, MBEDTLS_MODE_CTR, /**< The CTR cipher mode. */
MBEDTLS_MODE_GCM, MBEDTLS_MODE_GCM, /**< The GCM cipher mode. */
MBEDTLS_MODE_STREAM, MBEDTLS_MODE_STREAM, /**< The stream cipher mode. */
MBEDTLS_MODE_CCM, MBEDTLS_MODE_CCM, /**< The CCM cipher mode. */
} mbedtls_cipher_mode_t; } mbedtls_cipher_mode_t;
/** Supported cipher padding types. */ /** Supported cipher padding types. */
@ -163,8 +163,8 @@ typedef enum {
MBEDTLS_PADDING_PKCS7 = 0, /**< PKCS7 padding (default). */ MBEDTLS_PADDING_PKCS7 = 0, /**< PKCS7 padding (default). */
MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding. */ MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding. */
MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding. */ MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding. */
MBEDTLS_PADDING_ZEROS, /**< zero padding (not reversible). */ MBEDTLS_PADDING_ZEROS, /**< Zero padding (not reversible). */
MBEDTLS_PADDING_NONE, /**< never pad (full blocks only). */ MBEDTLS_PADDING_NONE, /**< Never pad (full blocks only). */
} mbedtls_cipher_padding_t; } mbedtls_cipher_padding_t;
/** Type of operation. */ /** Type of operation. */
@ -228,7 +228,8 @@ typedef struct {
*/ */
unsigned int iv_size; 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; int flags;
/** The block size, in Bytes. */ /** 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. * \param cipher_name Name of the cipher to search for.
* *
* \return The cipher information structure associated with the * \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 ); 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. * \param mode The cipher mode. For example, #MBEDTLS_MODE_CBC.
* *
* \return The cipher information structure associated with the * \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, const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values( const mbedtls_cipher_id_t cipher_id,
int key_bitlen, 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 ctx The context to initialize. May not be NULL.
* \param cipher_info The cipher to use. * \param cipher_info The cipher to use.
* *
* \return \c 0 on success, * \return \c 0 on success.
* #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure, * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure.
* #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
* cipher-specific context failed. * cipher-specific context failed.
* *
* \internal Currently, the function also clears the structure. * \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. * \param ctx The context of the cipher. Must be initialized.
* *
* \return The size of the blocks of the cipher, or zero if \p ctx * \return The size of the blocks of the cipher.
* has not been initialized. * \return 0 if \p ctx has not been initialized.
*/ */
static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_context_t *ctx ) 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. * \param ctx The context of the cipher. Must be initialized.
* *
* \return The mode of operation, or #MBEDTLS_MODE_NONE if * \return The mode of operation.
* \p ctx has not been initialized. * \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 ) 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. * \param ctx The context of the cipher. Must be initialized.
* *
* \return <ul><li>If no IV has been set: the recommended IV size. * \return The recommended IV size, if no IV has been set.
* 0 for ciphers not using IV or nonce.</li> * 0 for ciphers not using IV or nonce.
* <li>If IV has already been set: the actual size.</li></ul> * \return The actual size, if an IV has been set.
*/ */
static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ctx ) 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. * \param ctx The context of the cipher. Must be initialized.
* *
* \return The type of the cipher, or #MBEDTLS_CIPHER_NONE if * \return The type of the cipher.
* \p ctx has not been initialized. * \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 ) 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. * \param ctx The context of the cipher. Must be initialized.
* *
* \return The name of the cipher, or NULL if \p ctx has not * \return The name of the cipher.
* been not initialized. * \return NULL if \p ctx has not been not initialized.
*/ */
static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_t *ctx ) 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. * \param ctx The context of the cipher. Must be initialized.
* *
* \return The key length of the cipher in bits, or * \return The key length of the cipher in bits.
* #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been * \return #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been
* initialized. * initialized.
*/ */
static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t *ctx ) 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. * \param ctx The context of the cipher. Must be initialized.
* *
* \return The type of operation: #MBEDTLS_ENCRYPT or * \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. * has not been initialized.
*/ */
static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_cipher_context_t *ctx ) 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: * \param operation The operation that the key will be used for:
* #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT. * #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
* *
* \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if * \returns \c 0 on success.
* parameter verification fails, or a cipher-specific * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
* error code. * parameter verification fails.
* \return A cipher-specific error code.
*/ */
int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key, int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key,
int key_bitlen, const mbedtls_operation_t operation ); 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 ctx The generic cipher context.
* \param mode The padding mode. * \param mode The padding mode.
* *
* \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE * \returns \c 0 on success.
* if the selected padding mode is not supported, or * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
* #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode * if the selected padding mode is not supported.
* \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
* does not support padding. * does not support padding.
*/ */
int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_cipher_padding_t mode ); 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) * \brief This function sets the initialization vector (IV)
* or nonce. * 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 ctx The generic cipher context.
* \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. * \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. * \param iv_len The IV length for ciphers with variable-size IV.
* This parameter is discarded by ciphers with fixed-size IV. * This parameter is discarded by ciphers with fixed-size IV.
* *
* \returns \c 0 on success, or #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA * \returns \c 0 on success.
* * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on failure.
* \note Some ciphers do not use IVs nor nonce. For these
* ciphers, this function has no effect.
*/ */
int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx, int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len ); 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. * \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. * if parameter verification fails.
*/ */
int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx ); 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 The additional data to use.
* \param ad_len the Length of \p ad. * \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, int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx,
const unsigned char *ad, size_t ad_len ); 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 * Exception: For MBEDTLS_MODE_ECB, expects a single block
* in size. For example, 16 Bytes for AES. * 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 ctx The generic cipher context.
* \param input The buffer holding the input data. * \param input The buffer holding the input data.
* \param ilen The length of 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 * \param olen The length of the output data, to be updated with the
* actual number of Bytes written. * actual number of Bytes written.
* *
* \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if * \returns \c 0 on success.
* parameter verification fails, * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
* #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an * parameter verification fails.
* unsupported mode for a cipher, or a cipher-specific * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
* error code. * unsupported mode for a cipher.
* * \return 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.
*/ */
int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input, int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input,
size_t ilen, unsigned char *output, size_t *olen ); 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 output The buffer to write data to. Needs block_size available.
* \param olen The length of the data written to the \p output buffer. * \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 * \returns \c 0 on success.
* parameter verification fails, * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
* #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption * parameter verification fails.
* expected a full block but was not provided one, * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
* #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * expected a full block but was not provided one.
* while decrypting, or a cipher-specific error code * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
* on failure for any other reason. * while decrypting.
* \return A cipher-specific error code on failure for any other
* reason.
*/ */
int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx, int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx,
unsigned char *output, size_t *olen ); 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 The buffer to write the tag to.
* \param tag_len The length of the tag to write. * \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, int mbedtls_cipher_write_tag( mbedtls_cipher_context_t *ctx,
unsigned char *tag, size_t tag_len ); 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 The buffer holding the tag.
* \param tag_len The length of the tag to check. * \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, int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx,
const unsigned char *tag, size_t tag_len ); 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 * \note Some ciphers do not use IVs nor nonce. For these
* ciphers, use \p iv = NULL and \p iv_len = 0. * ciphers, use \p iv = NULL and \p iv_len = 0.
* *
* \returns \c 0 on success, or * \returns \c 0 on success.
* #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
* #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption * #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
* expected a full block but was not provided one, or * expected a full block but was not provided one.
* #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
* while decrypting, or a cipher-specific error code on * while decrypting.
* failure for any other reason. * \return A cipher-specific error code on failure for any other
* reason.
*/ */
int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx, int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len, 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 The buffer for the authentication tag.
* \param tag_len The desired length of the authentication tag. * \param tag_len The desired length of the authentication tag.
* *
* \returns \c 0 on success, or * \returns \c 0 on success.
* #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA.
* a cipher-specific error code. * \return A cipher-specific error code.
*/ */
int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len, 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. * \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 ctx The generic cipher context.
* \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. * \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. * \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 The buffer holding the authentication tag.
* \param tag_len The length of the authentication tag. * \param tag_len The length of the authentication tag.
* *
* \returns \c 0 on success, or * \returns \c 0 on success.
* #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA.
* #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic, * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic.
* or a cipher-specific error code on failure for any other reason. * \return 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.
*/ */
int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx, int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx,
const unsigned char *iv, size_t iv_len, const unsigned char *iv, size_t iv_len,