mirror/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-02-06 12:40:02 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'upstream-public/pr/1506' into development-proposed

Browse Source
This commit is contained in:
Jaeden Amero 2018-04-24 10:27:05 +01:00
commit f852f4c35b
1 changed files with 170 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

319
include/mbedtls/cipher.h
View File

@ -1,7 +1,9 @@
/** /**
* \file cipher.h * \file cipher.h
* *
* \brief 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 <dejong@fox-it.com> * \author Adriaan de Jong <dejong@fox-it.com>
*/ */
@ -69,93 +71,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 RC4 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. * ciphers instead.
*/ */
typedef enum { typedef enum {
MBEDTLS_CIPHER_ID_NONE = 0, MBEDTLS_CIPHER_ID_NONE = 0, /**< Placeholder to mark the end of cipher ID lists. */
MBEDTLS_CIPHER_ID_NULL, MBEDTLS_CIPHER_ID_NULL, /**< The identity cipher, treated as a stream cipher. */
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 Triple DES 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 RC4 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 RC4 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. * ciphers instead.
*/ */
typedef enum { typedef enum {
MBEDTLS_CIPHER_NONE = 0, MBEDTLS_CIPHER_NONE = 0, /**< Placeholder to mark the end of cipher-pair lists. */
MBEDTLS_CIPHER_NULL, MBEDTLS_CIPHER_NULL, /**< The identity stream cipher. */
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, /**< RC4 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, /**< The OFB cipher mode - unsupported. */
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 +165,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 +230,10 @@ 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. */ /** 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; int flags;
/** The block size, in Bytes. */ /** The block size, in Bytes. */
@ -299,7 +304,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 );
@ -310,7 +316,8 @@ const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher
* \param cipher_type Type of the cipher to search for. * \param cipher_type Type 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_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 ); const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type( const mbedtls_cipher_type_t cipher_type );
@ -325,7 +332,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,10 +360,11 @@ 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
* #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the * parameter-verification failure.
* cipher-specific context failed. * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
* cipher-specific context fails.
* *
* \internal Currently, the function also clears the structure. * \internal Currently, the function also clears the structure.
* In future versions, the caller will be required to call * In future versions, the caller will be required to call
@ -368,8 +377,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 +394,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 +411,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> * \return \c 0 for ciphers not using an IV or a 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 +431,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 +448,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 +464,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 )
@ -472,9 +481,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.
* #MBEDTLS_DECRYPT, or #MBEDTLS_OPERATION_NONE if \p ctx * \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 +503,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 * \return \c 0 on success.
* parameter verification fails, or a cipher-specific * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
* error code. * parameter-verification failure.
* \return A cipher-specific error code on failure.
*/ */
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 +521,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 * \return \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 +534,17 @@ 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 * \return \c 0 on success.
* * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
* \note Some ciphers do not use IVs nor nonce. For these * parameter-verification failure.
* 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,8 +554,9 @@ 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 * \return \c 0 on success.
* if parameter verification fails. * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
* parameter-verification failure.
*/ */
int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx ); int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx );
@ -557,7 +570,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 +587,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 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 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 +601,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 * \return \c 0 on success.
* parameter verification fails, * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
* #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an * parameter-verification failure.
* 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 on failure.
* \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 +621,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 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 * \return \c 0 on success.
* parameter verification fails, * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
* #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption * parameter-verification failure.
* expected a full block but was not provided one, * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption
* #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * expecting a full block but not receiving 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.
*/ */
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 +643,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 +658,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 +685,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 * \return \c 0 on success.
* #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
* #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption * parameter-verification failure.
* expected a full block but was not provided one, or * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption
* #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * expecting a full block but not receiving one.
* while decrypting, or a cipher-specific error code on * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
* failure for any other reason. * while decrypting.
* \return A cipher-specific error code on failure.
*/ */
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 +718,10 @@ 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 * \return \c 0 on success.
* #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
* a cipher-specific error code. * parameter-verification failure.
* \return A cipher-specific error code on failure.
*/ */
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 +733,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 +752,11 @@ 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 * \return \c 0 on success.
* #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
* #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic, * parameter-verification failure.
* or a cipher-specific error code on failure for any other reason. * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic.
* * \return A cipher-specific error code on failure.
* \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,