Commit 5c8af3c4 authored by Nathaniel Wesley Filardo's avatar Nathaniel Wesley Filardo Committed by Marcel Stör
Browse files

Update mbedTLS to 2.7.0 (#2267)

* mbedtls 2.7.0 (mbedtls-2.7.0-0-g32605dc8)

Wholesale import, with a few changes from earlier preserved through.
Ideally we would soon get to the point of having no divergences from
upstream.

* tls: add function to adjust mbedTLS debug level
parent f2d605d2
/** /**
* \file aes.h * \file aes.h
* *
* \brief AES block cipher * \brief The Advanced Encryption Standard (AES) specifies a FIPS-approved
* * cryptographic algorithm that can be used to protect electronic
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * data.
*
* The AES algorithm is a symmetric block cipher that can
* encrypt and decrypt information. For more information, see
* <em>FIPS Publication 197: Advanced Encryption Standard</em> and
* <em>ISO/IEC 18033-2:2006: Information technology -- Security
* techniques -- Encryption algorithms -- Part 2: Asymmetric
* ciphers</em>.
*/
/* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
* Licensed under the Apache License, Version 2.0 (the "License"); you may * Licensed under the Apache License, Version 2.0 (the "License"); you may
...@@ -18,8 +27,9 @@ ...@@ -18,8 +27,9 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
* *
* This file is part of mbed TLS (https://tls.mbed.org) * This file is part of Mbed TLS (https://tls.mbed.org)
*/ */
#ifndef MBEDTLS_AES_H #ifndef MBEDTLS_AES_H
#define MBEDTLS_AES_H #define MBEDTLS_AES_H
...@@ -33,12 +43,17 @@ ...@@ -33,12 +43,17 @@
#include <stdint.h> #include <stdint.h>
/* padlock.c and aesni.c rely on these values! */ /* padlock.c and aesni.c rely on these values! */
#define MBEDTLS_AES_ENCRYPT 1 #define MBEDTLS_AES_ENCRYPT 1 /**< AES encryption. */
#define MBEDTLS_AES_DECRYPT 0 #define MBEDTLS_AES_DECRYPT 0 /**< AES decryption. */
/* Error codes in range 0x0020-0x0022 */
#define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH -0x0020 /**< Invalid key length. */ #define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH -0x0020 /**< Invalid key length. */
#define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH -0x0022 /**< Invalid data input length. */ #define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH -0x0022 /**< Invalid data input length. */
/* Error codes in range 0x0023-0x0025 */
#define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE -0x0023 /**< Feature not available. For example, an unsupported AES key size. */
#define MBEDTLS_ERR_AES_HW_ACCEL_FAILED -0x0025 /**< AES hardware accelerator failed. */
#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \ #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
!defined(inline) && !defined(__cplusplus) !defined(inline) && !defined(__cplusplus)
#define inline __inline #define inline __inline
...@@ -53,68 +68,90 @@ extern "C" { ...@@ -53,68 +68,90 @@ extern "C" {
#endif #endif
/** /**
* \brief AES context structure * \brief The AES context-type definition.
*
* \note buf is able to hold 32 extra bytes, which can be used:
* - for alignment purposes if VIA padlock is used, and/or
* - to simplify key expansion in the 256-bit case by
* generating an extra round key
*/ */
typedef struct typedef struct
{ {
int nr; /*!< number of rounds */ int nr; /*!< The number of rounds. */
uint32_t *rk; /*!< AES round keys */ uint32_t *rk; /*!< AES round keys. */
uint32_t buf[68]; /*!< unaligned data */ uint32_t buf[68]; /*!< Unaligned data buffer. This buffer can
hold 32 extra Bytes, which can be used for
one of the following purposes:
<ul><li>Alignment if VIA padlock is
used.</li>
<li>Simplifying key expansion in the 256-bit
case by generating an extra round key.
</li></ul> */
} }
mbedtls_aes_context; mbedtls_aes_context;
/** /**
* \brief Initialize AES context * \brief This function initializes the specified AES context.
*
* It must be the first API called before using
* the context.
* *
* \param ctx AES context to be initialized * \param ctx The AES context to initialize.
*/ */
void mbedtls_aes_init( mbedtls_aes_context *ctx ); void mbedtls_aes_init( mbedtls_aes_context *ctx );
/** /**
* \brief Clear AES context * \brief This function releases and clears the specified AES context.
* *
* \param ctx AES context to be cleared * \param ctx The AES context to clear.
*/ */
void mbedtls_aes_free( mbedtls_aes_context *ctx ); void mbedtls_aes_free( mbedtls_aes_context *ctx );
/** /**
* \brief AES key schedule (encryption) * \brief This function sets the encryption key.
* *
* \param ctx AES context to be initialized * \param ctx The AES context to which the key should be bound.
* \param key encryption key * \param key The encryption key.
* \param keybits must be 128, 192 or 256 * \param keybits The size of data passed in bits. Valid options are:
* <ul><li>128 bits</li>
* <li>192 bits</li>
* <li>256 bits</li></ul>
* *
* \return 0 if successful, or MBEDTLS_ERR_AES_INVALID_KEY_LENGTH * \return \c 0 on success or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH
* on failure.
*/ */
int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key, int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key,
unsigned int keybits ); unsigned int keybits );
/** /**
* \brief AES key schedule (decryption) * \brief This function sets the decryption key.
* *
* \param ctx AES context to be initialized * \param ctx The AES context to which the key should be bound.
* \param key decryption key * \param key The decryption key.
* \param keybits must be 128, 192 or 256 * \param keybits The size of data passed. Valid options are:
* <ul><li>128 bits</li>
* <li>192 bits</li>
* <li>256 bits</li></ul>
* *
* \return 0 if successful, or MBEDTLS_ERR_AES_INVALID_KEY_LENGTH * \return \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
*/ */
int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key, int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key,
unsigned int keybits ); unsigned int keybits );
/** /**
* \brief AES-ECB block encryption/decryption * \brief This function performs an AES single-block encryption or
* * decryption operation.
* \param ctx AES context *
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT * It performs the operation defined in the \p mode parameter
* \param input 16-byte input block * (encrypt or decrypt), on the input data buffer defined in
* \param output 16-byte output block * the \p input parameter.
* *
* \return 0 if successful * mbedtls_aes_init(), and either mbedtls_aes_setkey_enc() or
* mbedtls_aes_setkey_dec() must be called before the first
* call to this API with the same context.
*
* \param ctx The AES context to use for encryption or decryption.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
* \param input The 16-Byte buffer holding the input data.
* \param output The 16-Byte buffer holding the output data.
* \return \c 0 on success.
*/ */
int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx, int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx,
int mode, int mode,
...@@ -123,26 +160,40 @@ int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx, ...@@ -123,26 +160,40 @@ int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx,
#if defined(MBEDTLS_CIPHER_MODE_CBC) #if defined(MBEDTLS_CIPHER_MODE_CBC)
/** /**
* \brief AES-CBC buffer encryption/decryption * \brief This function performs an AES-CBC encryption or decryption operation
* Length should be a multiple of the block * on full blocks.
* size (16 bytes) *
* It performs the operation defined in the \p mode
* parameter (encrypt/decrypt), on the input data buffer defined in
* the \p input parameter.
*
* It can be called as many times as needed, until all the input
* data is processed. mbedtls_aes_init(), and either
* mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called
* before the first call to this API with the same context.
*
* \note This function operates on aligned blocks, that is, the input size
* must be a multiple of the AES block size of 16 Bytes.
* *
* \note Upon exit, the content of the IV is updated so that you can * \note Upon exit, the content of the IV is updated so that you can
* call the function same function again on the following * call the same function again on the next
* block(s) of data and get the same result as if it was * block(s) of data and get the same result as if it was
* encrypted in one call. This allows a "streaming" usage. * encrypted in one call. This allows a "streaming" usage.
* If on the other hand you need to retain the contents of the * If you need to retain the contents of the IV, you should
* IV, you should either save it manually or use the cipher * either save it manually or use the cipher module instead.
* module instead.
* *
* \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
* \param length length of the input data
* \param iv initialization vector (updated after use)
* \param input buffer holding the input data
* \param output buffer holding the output data
* *
* \return 0 if successful, or MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH * \param ctx The AES context to use for encryption or decryption.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
* \param length The length of the input data in Bytes. This must be a
* multiple of the block size (16 Bytes).
* \param iv Initialization vector (updated after use).
* \param input The buffer holding the input data.
* \param output The buffer holding the output data.
*
* \return \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
* on failure.
*/ */
int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx, int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx,
int mode, int mode,
...@@ -154,29 +205,38 @@ int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx, ...@@ -154,29 +205,38 @@ int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx,
#if defined(MBEDTLS_CIPHER_MODE_CFB) #if defined(MBEDTLS_CIPHER_MODE_CFB)
/** /**
* \brief AES-CFB128 buffer encryption/decryption. * \brief This function performs an AES-CFB128 encryption or decryption
* operation.
*
* It performs the operation defined in the \p mode
* parameter (encrypt or decrypt), on the input data buffer
* defined in the \p input parameter.
* *
* Note: Due to the nature of CFB you should use the same key schedule for * For CFB, you must set up the context with mbedtls_aes_setkey_enc(),
* both encryption and decryption. So a context initialized with * regardless of whether you are performing an encryption or decryption
* mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. * operation, that is, regardless of the \p mode parameter. This is
* because CFB mode uses the same key schedule for encryption and
* decryption.
* *
* \note Upon exit, the content of the IV is updated so that you can * \note Upon exit, the content of the IV is updated so that you can
* call the function same function again on the following * call the same function again on the next
* block(s) of data and get the same result as if it was * block(s) of data and get the same result as if it was
* encrypted in one call. This allows a "streaming" usage. * encrypted in one call. This allows a "streaming" usage.
* If on the other hand you need to retain the contents of the * If you need to retain the contents of the
* IV, you should either save it manually or use the cipher * IV, you must either save it manually or use the cipher
* module instead. * module instead.
* *
* \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
* \param length length of the input data
* \param iv_off offset in IV (updated after use)
* \param iv initialization vector (updated after use)
* \param input buffer holding the input data
* \param output buffer holding the output data
* *
* \return 0 if successful * \param ctx The AES context to use for encryption or decryption.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT.
* \param length The length of the input data.
* \param iv_off The offset in IV (updated after use).
* \param iv The initialization vector (updated after use).
* \param input The buffer holding the input data.
* \param output The buffer holding the output data.
*
* \return \c 0 on success.
*/ */
int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx, int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx,
int mode, int mode,
...@@ -187,28 +247,36 @@ int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx, ...@@ -187,28 +247,36 @@ int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx,
unsigned char *output ); unsigned char *output );
/** /**
* \brief AES-CFB8 buffer encryption/decryption. * \brief This function performs an AES-CFB8 encryption or decryption
* operation.
*
* It performs the operation defined in the \p mode
* parameter (encrypt/decrypt), on the input data buffer defined
* in the \p input parameter.
* *
* Note: Due to the nature of CFB you should use the same key schedule for * Due to the nature of CFB, you must use the same key schedule for
* both encryption and decryption. So a context initialized with * both encryption and decryption operations. Therefore, you must
* mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. * use the context initialized with mbedtls_aes_setkey_enc() for
* both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
* *
* \note Upon exit, the content of the IV is updated so that you can * \note Upon exit, the content of the IV is updated so that you can
* call the function same function again on the following * call the same function again on the next
* block(s) of data and get the same result as if it was * block(s) of data and get the same result as if it was
* encrypted in one call. This allows a "streaming" usage. * encrypted in one call. This allows a "streaming" usage.
* If on the other hand you need to retain the contents of the * If you need to retain the contents of the
* IV, you should either save it manually or use the cipher * IV, you should either save it manually or use the cipher
* module instead. * module instead.
* *
* \param ctx AES context
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT
* \param length length of the input data
* \param iv initialization vector (updated after use)
* \param input buffer holding the input data
* \param output buffer holding the output data
* *
* \return 0 if successful * \param ctx The AES context to use for encryption or decryption.
* \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
* #MBEDTLS_AES_DECRYPT
* \param length The length of the input data.
* \param iv The initialization vector (updated after use).
* \param input The buffer holding the input data.
* \param output The buffer holding the output data.
*
* \return \c 0 on success.
*/ */
int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx, int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx,
int mode, int mode,
...@@ -220,26 +288,32 @@ int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx, ...@@ -220,26 +288,32 @@ int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx,
#if defined(MBEDTLS_CIPHER_MODE_CTR) #if defined(MBEDTLS_CIPHER_MODE_CTR)
/** /**
* \brief AES-CTR buffer encryption/decryption * \brief This function performs an AES-CTR encryption or decryption
* operation.
*
* This function performs the operation defined in the \p mode
* parameter (encrypt/decrypt), on the input data buffer
* defined in the \p input parameter.
* *
* Warning: You have to keep the maximum use of your counter in mind! * Due to the nature of CTR, you must use the same key schedule
* for both encryption and decryption operations. Therefore, you
* must use the context initialized with mbedtls_aes_setkey_enc()
* for both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
* *
* Note: Due to the nature of CTR you should use the same key schedule for * \warning You must keep the maximum use of your counter in mind.
* both encryption and decryption. So a context initialized with
* mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT.
* *
* \param ctx AES context * \param ctx The AES context to use for encryption or decryption.
* \param length The length of the data * \param length The length of the input data.
* \param nc_off The offset in the current stream_block (for resuming * \param nc_off The offset in the current \p stream_block, for
* within current cipher stream). The offset pointer to * resuming within the current cipher stream. The
* should be 0 at the start of a stream. * offset pointer should be 0 at the start of a stream.
* \param nonce_counter The 128-bit nonce and counter. * \param nonce_counter The 128-bit nonce and counter.
* \param stream_block The saved stream-block for resuming. Is overwritten * \param stream_block The saved stream block for resuming. This is
* by the function. * overwritten by the function.
* \param input The input data stream * \param input The buffer holding the input data.
* \param output The output data stream * \param output The buffer holding the output data.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx, int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx,
size_t length, size_t length,
...@@ -251,30 +325,30 @@ int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx, ...@@ -251,30 +325,30 @@ int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx,
#endif /* MBEDTLS_CIPHER_MODE_CTR */ #endif /* MBEDTLS_CIPHER_MODE_CTR */
/** /**
* \brief Internal AES block encryption function * \brief Internal AES block encryption function. This is only
* (Only exposed to allow overriding it, * exposed to allow overriding it using
* see MBEDTLS_AES_ENCRYPT_ALT) * \c MBEDTLS_AES_ENCRYPT_ALT.
* *
* \param ctx AES context * \param ctx The AES context to use for encryption.
* \param input Plaintext block * \param input The plaintext block.
* \param output Output (ciphertext) block * \param output The output (ciphertext) block.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_internal_aes_encrypt( mbedtls_aes_context *ctx, int mbedtls_internal_aes_encrypt( mbedtls_aes_context *ctx,
const unsigned char input[16], const unsigned char input[16],
unsigned char output[16] ); unsigned char output[16] );
/** /**
* \brief Internal AES block decryption function * \brief Internal AES block decryption function. This is only
* (Only exposed to allow overriding it, * exposed to allow overriding it using see
* see MBEDTLS_AES_DECRYPT_ALT) * \c MBEDTLS_AES_DECRYPT_ALT.
* *
* \param ctx AES context * \param ctx The AES context to use for decryption.
* \param input Ciphertext block * \param input The ciphertext block.
* \param output Output (plaintext) block * \param output The output (plaintext) block.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx, int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx,
const unsigned char input[16], const unsigned char input[16],
...@@ -290,11 +364,11 @@ int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx, ...@@ -290,11 +364,11 @@ int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx,
* \brief Deprecated internal AES block encryption function * \brief Deprecated internal AES block encryption function
* without return value. * without return value.
* *
* \deprecated Superseded by mbedtls_aes_encrypt_ext() in 2.5.0 * \deprecated Superseded by mbedtls_aes_encrypt_ext() in 2.5.0.
* *
* \param ctx AES context * \param ctx The AES context to use for encryption.
* \param input Plaintext block * \param input Plaintext block.
* \param output Output (ciphertext) block * \param output Output (ciphertext) block.
*/ */
MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx, MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx,
const unsigned char input[16], const unsigned char input[16],
...@@ -304,11 +378,11 @@ MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx, ...@@ -304,11 +378,11 @@ MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx,
* \brief Deprecated internal AES block decryption function * \brief Deprecated internal AES block decryption function
* without return value. * without return value.
* *
* \deprecated Superseded by mbedtls_aes_decrypt_ext() in 2.5.0 * \deprecated Superseded by mbedtls_aes_decrypt_ext() in 2.5.0.
* *
* \param ctx AES context * \param ctx The AES context to use for decryption.
* \param input Ciphertext block * \param input Ciphertext block.
* \param output Output (plaintext) block * \param output Output (plaintext) block.
*/ */
MBEDTLS_DEPRECATED void mbedtls_aes_decrypt( mbedtls_aes_context *ctx, MBEDTLS_DEPRECATED void mbedtls_aes_decrypt( mbedtls_aes_context *ctx,
const unsigned char input[16], const unsigned char input[16],
...@@ -330,9 +404,9 @@ extern "C" { ...@@ -330,9 +404,9 @@ extern "C" {
#endif #endif
/** /**
* \brief Checkup routine * \brief Checkup routine.
* *
* \return 0 if successful, or 1 if the test failed * \return \c 0 on success, or \c 1 on failure.
*/ */
int mbedtls_aes_self_test( int verbose ); int mbedtls_aes_self_test( int verbose );
......
...@@ -2,7 +2,8 @@ ...@@ -2,7 +2,8 @@
* \file aesni.h * \file aesni.h
* *
* \brief AES-NI for hardware AES acceleration on some Intel processors * \brief AES-NI for hardware AES acceleration on some Intel processors
* */
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
......
...@@ -3,6 +3,10 @@ ...@@ -3,6 +3,10 @@
* *
* \brief The ARCFOUR stream cipher * \brief The ARCFOUR stream cipher
* *
* \warning ARC4 is considered a weak cipher and its use constitutes a
* security risk. We recommend considering stronger ciphers instead.
*/
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
...@@ -19,6 +23,7 @@ ...@@ -19,6 +23,7 @@
* limitations under the License. * limitations under the License.
* *
* This file is part of mbed TLS (https://tls.mbed.org) * This file is part of mbed TLS (https://tls.mbed.org)
*
*/ */
#ifndef MBEDTLS_ARC4_H #ifndef MBEDTLS_ARC4_H
#define MBEDTLS_ARC4_H #define MBEDTLS_ARC4_H
...@@ -31,6 +36,8 @@ ...@@ -31,6 +36,8 @@
#include <stddef.h> #include <stddef.h>
#define MBEDTLS_ERR_ARC4_HW_ACCEL_FAILED -0x0019 /**< ARC4 hardware accelerator failed. */
#if !defined(MBEDTLS_ARC4_ALT) #if !defined(MBEDTLS_ARC4_ALT)
// Regular implementation // Regular implementation
// //
...@@ -41,6 +48,10 @@ extern "C" { ...@@ -41,6 +48,10 @@ extern "C" {
/** /**
* \brief ARC4 context structure * \brief ARC4 context structure
*
* \warning ARC4 is considered a weak cipher and its use constitutes a
* security risk. We recommend considering stronger ciphers instead.
*
*/ */
typedef struct typedef struct
{ {
...@@ -54,6 +65,11 @@ mbedtls_arc4_context; ...@@ -54,6 +65,11 @@ mbedtls_arc4_context;
* \brief Initialize ARC4 context * \brief Initialize ARC4 context
* *
* \param ctx ARC4 context to be initialized * \param ctx ARC4 context to be initialized
*
* \warning ARC4 is considered a weak cipher and its use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*
*/ */
void mbedtls_arc4_init( mbedtls_arc4_context *ctx ); void mbedtls_arc4_init( mbedtls_arc4_context *ctx );
...@@ -61,6 +77,11 @@ void mbedtls_arc4_init( mbedtls_arc4_context *ctx ); ...@@ -61,6 +77,11 @@ void mbedtls_arc4_init( mbedtls_arc4_context *ctx );
* \brief Clear ARC4 context * \brief Clear ARC4 context
* *
* \param ctx ARC4 context to be cleared * \param ctx ARC4 context to be cleared
*
* \warning ARC4 is considered a weak cipher and its use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*
*/ */
void mbedtls_arc4_free( mbedtls_arc4_context *ctx ); void mbedtls_arc4_free( mbedtls_arc4_context *ctx );
...@@ -70,6 +91,11 @@ void mbedtls_arc4_free( mbedtls_arc4_context *ctx ); ...@@ -70,6 +91,11 @@ void mbedtls_arc4_free( mbedtls_arc4_context *ctx );
* \param ctx ARC4 context to be setup * \param ctx ARC4 context to be setup
* \param key the secret key * \param key the secret key
* \param keylen length of the key, in bytes * \param keylen length of the key, in bytes
*
* \warning ARC4 is considered a weak cipher and its use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*
*/ */
void mbedtls_arc4_setup( mbedtls_arc4_context *ctx, const unsigned char *key, void mbedtls_arc4_setup( mbedtls_arc4_context *ctx, const unsigned char *key,
unsigned int keylen ); unsigned int keylen );
...@@ -83,6 +109,11 @@ void mbedtls_arc4_setup( mbedtls_arc4_context *ctx, const unsigned char *key, ...@@ -83,6 +109,11 @@ void mbedtls_arc4_setup( mbedtls_arc4_context *ctx, const unsigned char *key,
* \param output buffer for the output data * \param output buffer for the output data
* *
* \return 0 if successful * \return 0 if successful
*
* \warning ARC4 is considered a weak cipher and its use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*
*/ */
int mbedtls_arc4_crypt( mbedtls_arc4_context *ctx, size_t length, const unsigned char *input, int mbedtls_arc4_crypt( mbedtls_arc4_context *ctx, size_t length, const unsigned char *input,
unsigned char *output ); unsigned char *output );
...@@ -103,6 +134,11 @@ extern "C" { ...@@ -103,6 +134,11 @@ extern "C" {
* \brief Checkup routine * \brief Checkup routine
* *
* \return 0 if successful, or 1 if the test failed * \return 0 if successful, or 1 if the test failed
*
* \warning ARC4 is considered a weak cipher and its use constitutes a
* security risk. We recommend considering stronger ciphers
* instead.
*
*/ */
int mbedtls_arc4_self_test( int verbose ); int mbedtls_arc4_self_test( int verbose );
......
...@@ -2,7 +2,8 @@ ...@@ -2,7 +2,8 @@
* \file asn1.h * \file asn1.h
* *
* \brief Generic ASN.1 parsing * \brief Generic ASN.1 parsing
* */
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
...@@ -59,7 +60,7 @@ ...@@ -59,7 +60,7 @@
/** /**
* \name DER constants * \name DER constants
* These constants comply with DER encoded the ANS1 type tags. * These constants comply with the DER encoded ASN.1 type tags.
* DER encoding uses hexadecimal representation. * DER encoding uses hexadecimal representation.
* An example DER sequence is:\n * An example DER sequence is:\n
* - 0x02 -- tag indicating INTEGER * - 0x02 -- tag indicating INTEGER
......
...@@ -2,7 +2,8 @@ ...@@ -2,7 +2,8 @@
* \file asn1write.h * \file asn1write.h
* *
* \brief ASN.1 buffer writing functionality * \brief ASN.1 buffer writing functionality
* */
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
......
...@@ -2,7 +2,8 @@ ...@@ -2,7 +2,8 @@
* \file base64.h * \file base64.h
* *
* \brief RFC 1521 base64 encoding/decoding * \brief RFC 1521 base64 encoding/decoding
* */
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
......
...@@ -2,7 +2,8 @@ ...@@ -2,7 +2,8 @@
* \file bignum.h * \file bignum.h
* *
* \brief Multi-precision integer library * \brief Multi-precision integer library
* */
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
...@@ -70,7 +71,7 @@ ...@@ -70,7 +71,7 @@
* Maximum size of MPIs allowed in bits and bytes for user-MPIs. * Maximum size of MPIs allowed in bits and bytes for user-MPIs.
* ( Default: 512 bytes => 4096 bits, Maximum tested: 2048 bytes => 16384 bits ) * ( Default: 512 bytes => 4096 bits, Maximum tested: 2048 bytes => 16384 bits )
* *
* Note: Calculations can results temporarily in larger MPIs. So the number * Note: Calculations can temporarily result in larger MPIs. So the number
* of limbs required (MBEDTLS_MPI_MAX_LIMBS) is higher. * of limbs required (MBEDTLS_MPI_MAX_LIMBS) is higher.
*/ */
#define MBEDTLS_MPI_MAX_SIZE 1024 /**< Maximum number of bytes for usable MPIs. */ #define MBEDTLS_MPI_MAX_SIZE 1024 /**< Maximum number of bytes for usable MPIs. */
...@@ -683,6 +684,10 @@ int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi ...@@ -683,6 +684,10 @@ int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi
* *
* \return 0 if successful, * \return 0 if successful,
* MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
*
* \note The bytes obtained from the PRNG are interpreted
* as a big-endian representation of an MPI; this can
* be relevant in applications like deterministic ECDSA.
*/ */
int mbedtls_mpi_fill_random( mbedtls_mpi *X, size_t size, int mbedtls_mpi_fill_random( mbedtls_mpi *X, size_t size,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
......
...@@ -2,7 +2,8 @@ ...@@ -2,7 +2,8 @@
* \file blowfish.h * \file blowfish.h
* *
* \brief Blowfish block cipher * \brief Blowfish block cipher
* */
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
...@@ -40,6 +41,7 @@ ...@@ -40,6 +41,7 @@
#define MBEDTLS_BLOWFISH_BLOCKSIZE 8 /* Blowfish uses 64 bit blocks */ #define MBEDTLS_BLOWFISH_BLOCKSIZE 8 /* Blowfish uses 64 bit blocks */
#define MBEDTLS_ERR_BLOWFISH_INVALID_KEY_LENGTH -0x0016 /**< Invalid key length. */ #define MBEDTLS_ERR_BLOWFISH_INVALID_KEY_LENGTH -0x0016 /**< Invalid key length. */
#define MBEDTLS_ERR_BLOWFISH_HW_ACCEL_FAILED -0x0017 /**< Blowfish hardware accelerator failed. */
#define MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH -0x0018 /**< Invalid data input length. */ #define MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH -0x0018 /**< Invalid data input length. */
#if !defined(MBEDTLS_BLOWFISH_ALT) #if !defined(MBEDTLS_BLOWFISH_ALT)
......
...@@ -2,7 +2,8 @@ ...@@ -2,7 +2,8 @@
* \file bn_mul.h * \file bn_mul.h
* *
* \brief Multi-precision integer library * \brief Multi-precision integer library
* */
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
......
...@@ -2,7 +2,8 @@ ...@@ -2,7 +2,8 @@
* \file camellia.h * \file camellia.h
* *
* \brief Camellia block cipher * \brief Camellia block cipher
* */
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
...@@ -37,6 +38,7 @@ ...@@ -37,6 +38,7 @@
#define MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH -0x0024 /**< Invalid key length. */ #define MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH -0x0024 /**< Invalid key length. */
#define MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH -0x0026 /**< Invalid data input length. */ #define MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH -0x0026 /**< Invalid data input length. */
#define MBEDTLS_ERR_CAMELLIA_HW_ACCEL_FAILED -0x0027 /**< Camellia hardware accelerator failed. */
#if !defined(MBEDTLS_CAMELLIA_ALT) #if !defined(MBEDTLS_CAMELLIA_ALT)
// Regular implementation // Regular implementation
......
/** /**
* \file ccm.h * \file ccm.h
* *
* \brief Counter with CBC-MAC (CCM) for 128-bit block ciphers * \brief CCM combines Counter mode encryption with CBC-MAC authentication
* for 128-bit block ciphers.
* *
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Input to CCM includes the following elements:
* <ul><li>Payload - data that is both authenticated and encrypted.</li>
* <li>Associated data (Adata) - data that is authenticated but not
* encrypted, For example, a header.</li>
* <li>Nonce - A unique value that is assigned to the payload and the
* associated data.</li></ul>
*
*/
/*
* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
* Licensed under the Apache License, Version 2.0 (the "License"); you may * Licensed under the Apache License, Version 2.0 (the "License"); you may
...@@ -18,46 +28,54 @@ ...@@ -18,46 +28,54 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
* *
* This file is part of mbed TLS (https://tls.mbed.org) * This file is part of Mbed TLS (https://tls.mbed.org)
*/ */
#ifndef MBEDTLS_CCM_H #ifndef MBEDTLS_CCM_H
#define MBEDTLS_CCM_H #define MBEDTLS_CCM_H
#include "cipher.h" #include "cipher.h"
#define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D /**< Bad input parameters to function. */ #define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D /**< Bad input parameters to the function. */
#define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F /**< Authenticated decryption failed. */ #define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F /**< Authenticated decryption failed. */
#define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */
#if !defined(MBEDTLS_CCM_ALT)
// Regular implementation
//
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
/** /**
* \brief CCM context structure * \brief The CCM context-type definition. The CCM context is passed
* to the APIs called.
*/ */
typedef struct { typedef struct {
mbedtls_cipher_context_t cipher_ctx; /*!< cipher context used */ mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */
} }
mbedtls_ccm_context; mbedtls_ccm_context;
/** /**
* \brief Initialize CCM context (just makes references valid) * \brief This function initializes the specified CCM context,
* Makes the context ready for mbedtls_ccm_setkey() or * to make references valid, and prepare the context
* mbedtls_ccm_free(). * for mbedtls_ccm_setkey() or mbedtls_ccm_free().
* *
* \param ctx CCM context to initialize * \param ctx The CCM context to initialize.
*/ */
void mbedtls_ccm_init( mbedtls_ccm_context *ctx ); void mbedtls_ccm_init( mbedtls_ccm_context *ctx );
/** /**
* \brief CCM initialization (encryption and decryption) * \brief This function initializes the CCM context set in the
* \p ctx parameter and sets the encryption key.
* *
* \param ctx CCM context to be initialized * \param ctx The CCM context to initialize.
* \param cipher cipher to use (a 128-bit block cipher) * \param cipher The 128-bit block cipher to use.
* \param key encryption key * \param key The encryption key.
* \param keybits key size in bits (must be acceptable by the cipher) * \param keybits The key size in bits. This must be acceptable by the cipher.
* *
* \return 0 if successful, or a cipher specific error code * \return \c 0 on success, or a cipher-specific error code.
*/ */
int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx, int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx,
mbedtls_cipher_id_t cipher, mbedtls_cipher_id_t cipher,
...@@ -65,36 +83,37 @@ int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx, ...@@ -65,36 +83,37 @@ int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx,
unsigned int keybits ); unsigned int keybits );
/** /**
* \brief Free a CCM context and underlying cipher sub-context * \brief This function releases and clears the specified CCM context
* and underlying cipher sub-context.
* *
* \param ctx CCM context to free * \param ctx The CCM context to clear.
*/ */
void mbedtls_ccm_free( mbedtls_ccm_context *ctx ); void mbedtls_ccm_free( mbedtls_ccm_context *ctx );
/** /**
* \brief CCM buffer encryption * \brief This function encrypts a buffer using CCM.
* *
* \param ctx CCM context * \param ctx The CCM context to use for encryption.
* \param length length of the input data in bytes * \param length The length of the input data in Bytes.
* \param iv nonce (initialization vector) * \param iv Initialization vector (nonce).
* \param iv_len length of IV in bytes * \param iv_len The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
* must be 2, 3, 4, 5, 6, 7 or 8 * \param add The additional data field.
* \param add additional data * \param add_len The length of additional data in Bytes.
* \param add_len length of additional data in bytes * Must be less than 2^16 - 2^8.
* must be less than 2^16 - 2^8 * \param input The buffer holding the input data.
* \param input buffer holding the input data * \param output The buffer holding the output data.
* \param output buffer for holding the output data * Must be at least \p length Bytes wide.
* must be at least 'length' bytes wide * \param tag The buffer holding the tag.
* \param tag buffer for holding the tag * \param tag_len The length of the tag to generate in Bytes:
* \param tag_len length of the tag to generate in bytes * 4, 6, 8, 10, 14 or 16.
* must be 4, 6, 8, 10, 14 or 16 *
* * \note The tag is written to a separate buffer. To concatenate
* \note The tag is written to a separate buffer. To get the tag * the \p tag with the \p output, as done in <em>RFC-3610:
* concatenated with the output as in the CCM spec, use * Counter with CBC-MAC (CCM)</em>, use
* tag = output + length and make sure the output buffer is * \p tag = \p output + \p length, and make sure that the
* at least length + tag_len wide. * output buffer is at least \p length + \p tag_len wide.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
const unsigned char *iv, size_t iv_len, const unsigned char *iv, size_t iv_len,
...@@ -103,21 +122,22 @@ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, ...@@ -103,21 +122,22 @@ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
unsigned char *tag, size_t tag_len ); unsigned char *tag, size_t tag_len );
/** /**
* \brief CCM buffer authenticated decryption * \brief This function performs a CCM authenticated decryption of a
* * buffer.
* \param ctx CCM context *
* \param length length of the input data * \param ctx The CCM context to use for decryption.
* \param iv initialization vector * \param length The length of the input data in Bytes.
* \param iv_len length of IV * \param iv Initialization vector.
* \param add additional data * \param iv_len The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
* \param add_len length of additional data * \param add The additional data field.
* \param input buffer holding the input data * \param add_len The length of additional data in Bytes.
* \param output buffer for holding the output data * \param input The buffer holding the input data.
* \param tag buffer holding the tag * \param output The buffer holding the output data.
* \param tag_len length of the tag * \param tag The buffer holding the tag.
* * \param tag_len The length of the tag in Bytes.
* \return 0 if successful and authenticated, *
* MBEDTLS_ERR_CCM_AUTH_FAILED if tag does not match * \return 0 if successful and authenticated, or
* #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
*/ */
int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
const unsigned char *iv, size_t iv_len, const unsigned char *iv, size_t iv_len,
...@@ -125,11 +145,23 @@ int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, ...@@ -125,11 +145,23 @@ int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
const unsigned char *input, unsigned char *output, const unsigned char *input, unsigned char *output,
const unsigned char *tag, size_t tag_len ); const unsigned char *tag, size_t tag_len );
#ifdef __cplusplus
}
#endif
#else /* MBEDTLS_CCM_ALT */
#include "ccm_alt.h"
#endif /* MBEDTLS_CCM_ALT */
#ifdef __cplusplus
extern "C" {
#endif
#if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C) #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
/** /**
* \brief Checkup routine * \brief The CCM checkup routine.
* *
* \return 0 if successful, or 1 if the test failed * \return \c 0 on success, or \c 1 on failure.
*/ */
int mbedtls_ccm_self_test( int verbose ); int mbedtls_ccm_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */ #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
......
...@@ -2,7 +2,8 @@ ...@@ -2,7 +2,8 @@
* \file certs.h * \file certs.h
* *
* \brief Sample certificates and DHM parameters for testing * \brief Sample certificates and DHM parameters for testing
* */
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
......
...@@ -2,7 +2,8 @@ ...@@ -2,7 +2,8 @@
* \file check_config.h * \file check_config.h
* *
* \brief Consistency checks for configuration options * \brief Consistency checks for configuration options
* */
/*
* Copyright (C) 2006-2016, ARM Limited, All Rights Reserved * Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
......
/** /**
* \file cipher.h * \file cipher.h
* *
* \brief Generic cipher wrapper. * \brief The generic cipher wrapper.
* *
* \author Adriaan de Jong <dejong@fox-it.com> * \author Adriaan de Jong <dejong@fox-it.com>
* */
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved /*
* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
* Licensed under the Apache License, Version 2.0 (the "License"); you may * Licensed under the Apache License, Version 2.0 (the "License"); you may
...@@ -20,7 +21,7 @@ ...@@ -20,7 +21,7 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
* *
* This file is part of mbed TLS (https://tls.mbed.org) * This file is part of Mbed TLS (https://tls.mbed.org)
*/ */
#ifndef MBEDTLS_CIPHER_H #ifndef MBEDTLS_CIPHER_H
...@@ -52,20 +53,28 @@ ...@@ -52,20 +53,28 @@
#endif #endif
#define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080 /**< The selected feature is not available. */ #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080 /**< The selected feature is not available. */
#define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100 /**< Bad input parameters to function. */ #define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100 /**< Bad input parameters. */
#define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180 /**< Failed to allocate memory. */ #define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180 /**< Failed to allocate memory. */
#define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200 /**< Input data contains invalid padding and is rejected. */ #define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200 /**< Input data contains invalid padding and is rejected. */
#define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280 /**< Decryption of block requires a full block. */ #define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280 /**< Decryption of block requires a full block. */
#define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300 /**< Authentication failed (for AEAD modes). */ #define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300 /**< Authentication failed (for AEAD modes). */
#define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380 /**< The context is invalid, eg because it was free()ed. */ #define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380 /**< The context is invalid. For example, because it was freed. */
#define MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED -0x6400 /**< Cipher hardware accelerator failed. */
#define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01 /**< Cipher accepts IVs of variable length */ #define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01 /**< Cipher accepts IVs of variable length. */
#define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02 /**< Cipher accepts keys of variable length */ #define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02 /**< Cipher accepts keys of variable length. */
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
/**
* \brief An enumeration of supported ciphers.
*
* \warning ARC4 and DES are considered weak ciphers and their use
* constitutes a security risk. We recommend considering stronger
* ciphers instead.
*/
typedef enum { typedef enum {
MBEDTLS_CIPHER_ID_NONE = 0, MBEDTLS_CIPHER_ID_NONE = 0,
MBEDTLS_CIPHER_ID_NULL, MBEDTLS_CIPHER_ID_NULL,
...@@ -77,6 +86,13 @@ typedef enum { ...@@ -77,6 +86,13 @@ typedef enum {
MBEDTLS_CIPHER_ID_ARC4, MBEDTLS_CIPHER_ID_ARC4,
} mbedtls_cipher_id_t; } mbedtls_cipher_id_t;
/**
* \brief An enumeration of supported (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 { typedef enum {
MBEDTLS_CIPHER_NONE = 0, MBEDTLS_CIPHER_NONE = 0,
MBEDTLS_CIPHER_NULL, MBEDTLS_CIPHER_NULL,
...@@ -129,6 +145,7 @@ typedef enum { ...@@ -129,6 +145,7 @@ typedef enum {
MBEDTLS_CIPHER_CAMELLIA_256_CCM, MBEDTLS_CIPHER_CAMELLIA_256_CCM,
} mbedtls_cipher_type_t; } mbedtls_cipher_type_t;
/** Supported cipher modes. */
typedef enum { typedef enum {
MBEDTLS_MODE_NONE = 0, MBEDTLS_MODE_NONE = 0,
MBEDTLS_MODE_ECB, MBEDTLS_MODE_ECB,
...@@ -141,14 +158,16 @@ typedef enum { ...@@ -141,14 +158,16 @@ typedef enum {
MBEDTLS_MODE_CCM, MBEDTLS_MODE_CCM,
} mbedtls_cipher_mode_t; } mbedtls_cipher_mode_t;
/** Supported cipher padding types. */
typedef enum { 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. */
typedef enum { typedef enum {
MBEDTLS_OPERATION_NONE = -1, MBEDTLS_OPERATION_NONE = -1,
MBEDTLS_DECRYPT = 0, MBEDTLS_DECRYPT = 0,
...@@ -156,19 +175,19 @@ typedef enum { ...@@ -156,19 +175,19 @@ typedef enum {
} mbedtls_operation_t; } mbedtls_operation_t;
enum { enum {
/** Undefined key length */ /** Undefined key length. */
MBEDTLS_KEY_LENGTH_NONE = 0, MBEDTLS_KEY_LENGTH_NONE = 0,
/** Key length, in bits (including parity), for DES keys */ /** Key length, in bits (including parity), for DES keys. */
MBEDTLS_KEY_LENGTH_DES = 64, MBEDTLS_KEY_LENGTH_DES = 64,
/** Key length, in bits (including parity), for DES in two key EDE */ /** Key length in bits, including parity, for DES in two-key EDE. */
MBEDTLS_KEY_LENGTH_DES_EDE = 128, MBEDTLS_KEY_LENGTH_DES_EDE = 128,
/** Key length, in bits (including parity), for DES in three-key EDE */ /** Key length in bits, including parity, for DES in three-key EDE. */
MBEDTLS_KEY_LENGTH_DES_EDE3 = 192, MBEDTLS_KEY_LENGTH_DES_EDE3 = 192,
}; };
/** Maximum length of any IV, in bytes */ /** Maximum length of any IV, in Bytes. */
#define MBEDTLS_MAX_IV_LENGTH 16 #define MBEDTLS_MAX_IV_LENGTH 16
/** Maximum block size of any cipher, in bytes */ /** Maximum block size of any cipher, in Bytes. */
#define MBEDTLS_MAX_BLOCK_LENGTH 16 #define MBEDTLS_MAX_BLOCK_LENGTH 16
/** /**
...@@ -182,33 +201,40 @@ typedef struct mbedtls_cipher_base_t mbedtls_cipher_base_t; ...@@ -182,33 +201,40 @@ typedef struct mbedtls_cipher_base_t mbedtls_cipher_base_t;
typedef struct mbedtls_cmac_context_t mbedtls_cmac_context_t; typedef struct mbedtls_cmac_context_t mbedtls_cmac_context_t;
/** /**
* Cipher information. Allows cipher functions to be called in a generic way. * Cipher information. Allows calling cipher functions
* in a generic way.
*/ */
typedef struct { typedef struct {
/** Full cipher identifier (e.g. MBEDTLS_CIPHER_AES_256_CBC) */ /** Full cipher identifier. For example,
* MBEDTLS_CIPHER_AES_256_CBC.
*/
mbedtls_cipher_type_t type; mbedtls_cipher_type_t type;
/** Cipher mode (e.g. MBEDTLS_MODE_CBC) */ /** The cipher mode. For example, MBEDTLS_MODE_CBC. */
mbedtls_cipher_mode_t mode; mbedtls_cipher_mode_t mode;
/** Cipher key length, in bits (default length for variable sized ciphers) /** The cipher key length, in bits. This is the
* (Includes parity bits for ciphers like DES) */ * default length for variable sized ciphers.
* Includes parity bits for ciphers like DES.
*/
unsigned int key_bitlen; unsigned int key_bitlen;
/** Name of the cipher */ /** Name of the cipher. */
const char * name; const char * name;
/** IV/NONCE size, in bytes. /** IV or nonce size, in Bytes.
* For cipher that accept many sizes: recommended size */ * For ciphers that accept variable IV sizes,
* this is the recommended size.
*/
unsigned int iv_size; unsigned int iv_size;
/** Flags for variable IV size, variable key size, etc. */ /** Flags to set. For example, if the cipher supports variable IV sizes or variable key sizes. */
int flags; int flags;
/** block size, in bytes */ /** The block size, in Bytes. */
unsigned int block_size; unsigned int block_size;
/** Base cipher information and functions */ /** Struct for base cipher information and functions. */
const mbedtls_cipher_base_t *base; const mbedtls_cipher_base_t *base;
} mbedtls_cipher_info_t; } mbedtls_cipher_info_t;
...@@ -217,125 +243,133 @@ typedef struct { ...@@ -217,125 +243,133 @@ typedef struct {
* Generic cipher context. * Generic cipher context.
*/ */
typedef struct { typedef struct {
/** Information about the associated cipher */ /** Information about the associated cipher. */
const mbedtls_cipher_info_t *cipher_info; const mbedtls_cipher_info_t *cipher_info;
/** Key length to use */ /** Key length to use. */
int key_bitlen; int key_bitlen;
/** Operation that the context's key has been initialised for */ /** Operation that the key of the context has been
* initialized for.
*/
mbedtls_operation_t operation; mbedtls_operation_t operation;
#if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING) #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
/** Padding functions to use, if relevant for cipher mode */ /** Padding functions to use, if relevant for
* the specific cipher mode.
*/
void (*add_padding)( unsigned char *output, size_t olen, size_t data_len ); void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len ); int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
#endif #endif
/** Buffer for data that hasn't been encrypted yet */ /** Buffer for input that has not been processed yet. */
unsigned char unprocessed_data[MBEDTLS_MAX_BLOCK_LENGTH]; unsigned char unprocessed_data[MBEDTLS_MAX_BLOCK_LENGTH];
/** Number of bytes that still need processing */ /** Number of Bytes that have not been processed yet. */
size_t unprocessed_len; size_t unprocessed_len;
/** Current IV or NONCE_COUNTER for CTR-mode */ /** Current IV or NONCE_COUNTER for CTR-mode. */
unsigned char iv[MBEDTLS_MAX_IV_LENGTH]; unsigned char iv[MBEDTLS_MAX_IV_LENGTH];
/** IV size in bytes (for ciphers with variable-length IVs) */ /** IV size in Bytes, for ciphers with variable-length IVs. */
size_t iv_size; size_t iv_size;
/** Cipher-specific context */ /** The cipher-specific context. */
void *cipher_ctx; void *cipher_ctx;
#if defined(MBEDTLS_CMAC_C) #if defined(MBEDTLS_CMAC_C)
/** CMAC Specific context */ /** CMAC-specific context. */
mbedtls_cmac_context_t *cmac_ctx; mbedtls_cmac_context_t *cmac_ctx;
#endif #endif
} mbedtls_cipher_context_t; } mbedtls_cipher_context_t;
/** /**
* \brief Returns the list of ciphers supported by the generic cipher module. * \brief This function retrieves the list of ciphers supported by the generic
* cipher module.
* *
* \return a statically allocated array of ciphers, the last entry * \return A statically-allocated array of ciphers. The last entry
* is 0. * is zero.
*/ */
const int *mbedtls_cipher_list( void ); const int *mbedtls_cipher_list( void );
/** /**
* \brief Returns the cipher information structure associated * \brief This function retrieves the cipher-information
* with the given cipher name. * structure associated with the given cipher name.
* *
* \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 cipher_name, or NULL if not found. * given \p cipher_name, or NULL if 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 );
/** /**
* \brief Returns the cipher information structure associated * \brief This function retrieves the cipher-information
* with the given cipher type. * structure associated with the given cipher type.
* *
* \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 cipher_type, or NULL if not found. * given \p cipher_type, or NULL if 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 );
/** /**
* \brief Returns the cipher information structure associated * \brief This function retrieves the cipher-information
* with the given cipher id, key size and mode. * structure associated with the given cipher ID,
* key size and mode.
* *
* \param cipher_id Id of the cipher to search for * \param cipher_id The ID of the cipher to search for. For example,
* (e.g. MBEDTLS_CIPHER_ID_AES) * #MBEDTLS_CIPHER_ID_AES.
* \param key_bitlen Length of the key in bits * \param key_bitlen The length of the key in bits.
* \param mode Cipher mode (e.g. 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 cipher_type, or NULL if not found. * given \p cipher_id, or NULL if 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,
const mbedtls_cipher_mode_t mode ); const mbedtls_cipher_mode_t mode );
/** /**
* \brief Initialize a cipher_context (as NONE) * \brief This function initializes a \p cipher_context as NONE.
*/ */
void mbedtls_cipher_init( mbedtls_cipher_context_t *ctx ); void mbedtls_cipher_init( mbedtls_cipher_context_t *ctx );
/** /**
* \brief Free and clear the cipher-specific context of ctx. * \brief This function frees and clears the cipher-specific
* Freeing ctx itself remains the responsibility of the * context of \p ctx. Freeing \p ctx itself remains the
* caller. * responsibility of the caller.
*/ */
void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx ); void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx );
/** /**
* \brief Initialises and fills the cipher context structure with * \brief This function initializes and fills the cipher-context
* the appropriate values. * structure with the appropriate values. It also clears
* * the structure.
* \note Currently also clears structure. In future versions you
* will be required to call mbedtls_cipher_init() on the structure
* first.
* *
* \param ctx context to initialise. May not be NULL. * \param ctx The context to initialize. May not be NULL.
* \param cipher_info cipher to use. * \param cipher_info The cipher to use.
* *
* \return 0 on success, * \return \c 0 on success,
* MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure, * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
* MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the * #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.
* In future versions, the caller will be required to call
* mbedtls_cipher_init() on the structure first.
*/ */
int mbedtls_cipher_setup( mbedtls_cipher_context_t *ctx, const mbedtls_cipher_info_t *cipher_info ); int mbedtls_cipher_setup( mbedtls_cipher_context_t *ctx, const mbedtls_cipher_info_t *cipher_info );
/** /**
* \brief Returns the block size of the given cipher. * \brief This function returns the block size of the given cipher.
* *
* \param ctx cipher's context. Must have been initialised. * \param ctx The context of the cipher. Must be initialized.
* *
* \return size of the cipher's blocks, or 0 if ctx has not been * \return The size of the blocks of the cipher, or zero if \p ctx
* initialised. * 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 )
{ {
...@@ -346,13 +380,13 @@ static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_c ...@@ -346,13 +380,13 @@ static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_c
} }
/** /**
* \brief Returns the mode of operation for the cipher. * \brief This function returns the mode of operation for
* (e.g. MBEDTLS_MODE_CBC) * the cipher. For example, MBEDTLS_MODE_CBC.
* *
* \param ctx cipher's context. Must have been initialised. * \param ctx The context of the cipher. Must be initialized.
* *
* \return mode of operation, or MBEDTLS_MODE_NONE if ctx * \return The mode of operation, or #MBEDTLS_MODE_NONE if
* has not been initialised. * \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 )
{ {
...@@ -363,13 +397,14 @@ static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtl ...@@ -363,13 +397,14 @@ static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtl
} }
/** /**
* \brief Returns the size of the cipher's IV/NONCE in bytes. * \brief This function returns the size of the IV or nonce
* of the cipher, in Bytes.
* *
* \param ctx cipher's context. Must have been initialised. * \param ctx The context of the cipher. Must be initialized.
* *
* \return If IV has not been set yet: (recommended) IV size * \return <ul><li>If no IV has been set: the recommended IV size.
* (0 for ciphers not using IV/NONCE). * 0 for ciphers not using IV or nonce.</li>
* If IV has already been set: actual size. * <li>If IV has already been set: the actual size.</li></ul>
*/ */
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 )
{ {
...@@ -383,12 +418,12 @@ static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ct ...@@ -383,12 +418,12 @@ static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t *ct
} }
/** /**
* \brief Returns the type of the given cipher. * \brief This function returns the type of the given cipher.
* *
* \param ctx cipher's context. Must have been initialised. * \param ctx The context of the cipher. Must be initialized.
* *
* \return type of the cipher, or MBEDTLS_CIPHER_NONE if ctx has * \return The type of the cipher, or #MBEDTLS_CIPHER_NONE if
* not been initialised. * \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 )
{ {
...@@ -399,11 +434,13 @@ static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( const mbedtls_ciphe ...@@ -399,11 +434,13 @@ static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( const mbedtls_ciphe
} }
/** /**
* \brief Returns the name of the given cipher, as a string. * \brief This function returns the name of the given cipher
* as a string.
* *
* \param ctx cipher's context. Must have been initialised. * \param ctx The context of the cipher. Must be initialized.
* *
* \return name of the cipher, or NULL if ctx was not initialised. * \return The name of the cipher, or 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 )
{ {
...@@ -414,13 +451,13 @@ static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_ ...@@ -414,13 +451,13 @@ static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_
} }
/** /**
* \brief Returns the key length of the cipher. * \brief This function returns the key length of the cipher.
* *
* \param ctx cipher's context. Must have been initialised. * \param ctx The context of the cipher. Must be initialized.
* *
* \return cipher's key length, in bits, or * \return The key length of the cipher in bits, or
* MBEDTLS_KEY_LENGTH_NONE if ctx has not been * #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been
* initialised. * 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 )
{ {
...@@ -431,13 +468,13 @@ static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t ...@@ -431,13 +468,13 @@ static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t
} }
/** /**
* \brief Returns the operation of the given cipher. * \brief This function returns the operation of the given cipher.
* *
* \param ctx cipher's context. Must have been initialised. * \param ctx The context of the cipher. Must be initialized.
* *
* \return operation (MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT), * \return The type of operation: #MBEDTLS_ENCRYPT or
* or MBEDTLS_OPERATION_NONE if ctx has not been * #MBEDTLS_DECRYPT, or #MBEDTLS_OPERATION_NONE if \p ctx
* initialised. * 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 )
{ {
...@@ -448,18 +485,18 @@ static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_ci ...@@ -448,18 +485,18 @@ static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_ci
} }
/** /**
* \brief Set the key to use with the given context. * \brief This function sets the key to use with the given context.
* *
* \param ctx generic cipher context. May not be NULL. Must have been * \param ctx The generic cipher context. May not be NULL. Must have
* initialised using cipher_context_from_type or * been initialized using mbedtls_cipher_info_from_type()
* cipher_context_from_string. * or mbedtls_cipher_info_from_string().
* \param key The key to use. * \param key The key to use.
* \param key_bitlen key length to use, in bits. * \param key_bitlen The key length to use, in bits.
* \param operation Operation that the key will be used for, either * \param operation The operation that the key will be used for:
* MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT. * #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
* *
* \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
* parameter verification fails or a cipher specific * parameter verification fails, or a cipher-specific
* error code. * 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,
...@@ -467,170 +504,176 @@ int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *k ...@@ -467,170 +504,176 @@ int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *k
#if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING) #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
/** /**
* \brief Set padding mode, for cipher modes that use padding. * \brief This function sets the padding mode, for cipher modes
* (Default: PKCS7 padding.) * that use padding.
*
* The default passing mode is PKCS7 padding.
* *
* \param ctx generic cipher context * \param ctx The generic cipher context.
* \param mode padding mode * \param mode The padding mode.
* *
* \returns 0 on success, MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
* if selected padding mode is not supported, or * if the selected padding mode is not supported, or
* MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode * #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 );
#endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */ #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */
/** /**
* \brief Set the initialization vector (IV) or nonce * \brief This function sets the initialization vector (IV)
* or nonce.
* *
* \param ctx generic cipher context * \param ctx The generic cipher context.
* \param iv 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 IV length for ciphers with variable-size IV; * \param iv_len The IV length for ciphers with variable-size IV.
* discarded by ciphers with fixed-size IV. * This parameter is discarded by ciphers with fixed-size IV.
* *
* \returns 0 on success, or MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA * \returns \c 0 on success, or #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
* *
* \note Some ciphers don't use IVs nor NONCE. For these * \note Some ciphers do not use IVs nor nonce. For these
* ciphers, this function has no effect. * 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 );
/** /**
* \brief Finish preparation of the given context * \brief This function resets the cipher state.
* *
* \param ctx generic cipher context * \param ctx The generic cipher context.
* *
* \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA * \returns \c 0 on success, #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 );
#if defined(MBEDTLS_GCM_C) #if defined(MBEDTLS_GCM_C)
/** /**
* \brief Add additional data (for AEAD ciphers). * \brief This function adds additional data for AEAD ciphers.
* Currently only supported with GCM. * Only supported with GCM. Must be called
* Must be called exactly once, after mbedtls_cipher_reset(). * exactly once, after mbedtls_cipher_reset().
* *
* \param ctx generic cipher context * \param ctx The generic cipher context.
* \param ad Additional data to use. * \param ad The additional data to use.
* \param ad_len Length of ad. * \param ad_len the Length of \p ad.
* *
* \return 0 on success, or a specific error code. * \return \c 0 on success, or 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 );
#endif /* MBEDTLS_GCM_C */ #endif /* MBEDTLS_GCM_C */
/** /**
* \brief Generic cipher update function. Encrypts/decrypts * \brief The generic cipher update function. It encrypts or
* using the given cipher context. Writes as many block * decrypts using the given cipher context. Writes as
* size'd blocks of data as possible to output. Any data * many block-sized blocks of data as possible to output.
* that cannot be written immediately will either be added * Any data that cannot be written immediately is either
* to the next block, or flushed when cipher_final is * added to the next block, or flushed when
* called. * mbedtls_cipher_finish() is called.
* Exception: for MBEDTLS_MODE_ECB, expects single block * Exception: For MBEDTLS_MODE_ECB, expects a single block
* in size (e.g. 16 bytes for AES) * in size. For example, 16 Bytes for AES.
* *
* \param ctx generic cipher context * \param ctx The generic cipher context.
* \param input buffer holding the input data * \param input The buffer holding the input data.
* \param ilen length of the input data * \param ilen The length of the input data.
* \param output buffer for the output data. Should be able to hold at * \param output The buffer for the output data. Must be able to hold at
* least ilen + block_size. Cannot be the same buffer as * least \p ilen + block_size. Must not be the same buffer
* input! * as input.
* \param olen length of the output data, will be filled 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 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
* parameter verification fails, * parameter verification fails,
* MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an * #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
* unsupported mode for a cipher or a cipher specific * unsupported mode for a cipher, or a cipher-specific
* error code. * error code.
* *
* \note If the underlying cipher is GCM, all calls to this * \note If the underlying cipher is GCM, all calls to this
* function, except the last one before mbedtls_cipher_finish(), * function, except the last one before
* must have ilen a multiple of the block size. * 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 );
/** /**
* \brief Generic cipher finalisation function. If data still * \brief The generic cipher finalization function. If data still
* needs to be flushed from an incomplete block, data * needs to be flushed from an incomplete block, the data
* contained within it will be padded with the size of * contained in it is padded to the size of
* the last block, and written to the output buffer. * the last block, and written to the \p output buffer.
* *
* \param ctx Generic cipher context * \param ctx The generic cipher context.
* \param output buffer to write data to. Needs block_size available. * \param output The buffer to write data to. Needs block_size available.
* \param olen length of the data written to the output buffer. * \param olen The length of the data written to the \p output buffer.
* *
* \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
* parameter verification fails, * parameter verification fails,
* 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, * expected a full block but was not provided one,
* MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
* while decrypting or a cipher specific error code. * while decrypting, or 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 );
#if defined(MBEDTLS_GCM_C) #if defined(MBEDTLS_GCM_C)
/** /**
* \brief Write tag for AEAD ciphers. * \brief This function writes a tag for AEAD ciphers.
* Currently only supported with GCM. * Only supported with GCM.
* Must be called after mbedtls_cipher_finish(). * Must be called after mbedtls_cipher_finish().
* *
* \param ctx Generic cipher context * \param ctx The generic cipher context.
* \param tag buffer to write the tag * \param tag The buffer to write the tag to.
* \param tag_len Length of the tag to write * \param tag_len The length of the tag to write.
* *
* \return 0 on success, or a specific error code. * \return \c 0 on success, or 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 );
/** /**
* \brief Check tag for AEAD ciphers. * \brief This function checks the tag for AEAD ciphers.
* Currently only supported with GCM. * Only supported with GCM.
* Must be called after mbedtls_cipher_finish(). * Must be called after mbedtls_cipher_finish().
* *
* \param ctx Generic cipher context * \param ctx The generic cipher context.
* \param tag Buffer holding the tag * \param tag The buffer holding the tag.
* \param tag_len Length of the tag to check * \param tag_len The length of the tag to check.
* *
* \return 0 on success, or a specific error code. * \return \c 0 on success, or 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 );
#endif /* MBEDTLS_GCM_C */ #endif /* MBEDTLS_GCM_C */
/** /**
* \brief Generic all-in-one encryption/decryption * \brief The generic all-in-one encryption/decryption function,
* (for all ciphers except AEAD constructs). * for all ciphers except AEAD constructs.
* *
* \param ctx generic cipher context * \param ctx The generic cipher context.
* \param iv 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 IV length for ciphers with variable-size IV; * \param iv_len The IV length for ciphers with variable-size IV.
* discarded by ciphers with fixed-size IV. * This parameter is discarded by ciphers with fixed-size
* \param input buffer holding the input data * IV.
* \param ilen length of the input data * \param input The buffer holding the input data.
* \param output buffer for the output data. Should be able to hold at * \param ilen The length of the input data.
* least ilen + block_size. Cannot be the same buffer as * \param output The buffer for the output data. Must be able to hold at
* input! * least \p ilen + block_size. Must not be the same buffer
* \param olen length of the output data, will be filled with the * as input.
* actual number of bytes written. * \param olen The length of the output data, to be updated with the
* * actual number of Bytes written.
* \note Some ciphers don't use IVs nor NONCE. For these *
* ciphers, use iv = NULL and iv_len = 0. * \note Some ciphers do not use IVs nor nonce. For these
* * ciphers, use \p iv = NULL and \p iv_len = 0.
* \returns 0 on success, or *
* MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or * \returns \c 0 on success, or
* MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption * #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 * expected a full block but was not provided one, or
* MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding * #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
* while decrypting, or * while decrypting, or a cipher-specific error code on
* a cipher specific error code. * 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,
...@@ -639,26 +682,26 @@ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx, ...@@ -639,26 +682,26 @@ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx,
#if defined(MBEDTLS_CIPHER_MODE_AEAD) #if defined(MBEDTLS_CIPHER_MODE_AEAD)
/** /**
* \brief Generic autenticated encryption (AEAD ciphers). * \brief The generic autenticated encryption (AEAD) function.
* *
* \param ctx generic cipher context * \param ctx The generic cipher context.
* \param iv 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 IV length for ciphers with variable-size IV; * \param iv_len The IV length for ciphers with variable-size IV.
* discarded by ciphers with fixed-size IV. * This parameter is discarded by ciphers with fixed-size IV.
* \param ad Additional data to authenticate. * \param ad The additional data to authenticate.
* \param ad_len Length of ad. * \param ad_len The length of \p ad.
* \param input buffer holding the input data * \param input The buffer holding the input data.
* \param ilen length of the input data * \param ilen The length of the input data.
* \param output buffer for the output data. * \param output The buffer for the output data.
* Should be able to hold at least ilen. * Must be able to hold at least \p ilen.
* \param olen length of the output data, will be filled 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.
* \param tag buffer for the authentication tag * \param tag The buffer for the authentication tag.
* \param tag_len desired tag length * \param tag_len The desired length of the authentication tag.
* *
* \returns 0 on success, or * \returns \c 0 on success, or
* MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
* a cipher specific error code. * 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,
...@@ -668,31 +711,31 @@ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, ...@@ -668,31 +711,31 @@ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx,
unsigned char *tag, size_t tag_len ); unsigned char *tag, size_t tag_len );
/** /**
* \brief Generic autenticated decryption (AEAD ciphers). * \brief The generic autenticated decryption (AEAD) function.
* *
* \param ctx generic cipher context * \param ctx The generic cipher context.
* \param iv 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 IV length for ciphers with variable-size IV; * \param iv_len The IV length for ciphers with variable-size IV.
* discarded by ciphers with fixed-size IV. * This parameter is discarded by ciphers with fixed-size IV.
* \param ad Additional data to be authenticated. * \param ad The additional data to be authenticated.
* \param ad_len Length of ad. * \param ad_len The length of \p ad.
* \param input buffer holding the input data * \param input The buffer holding the input data.
* \param ilen length of the input data * \param ilen The length of the input data.
* \param output buffer for the output data. * \param output The buffer for the output data.
* Should be able to hold at least ilen. * Must be able to hold at least \p ilen.
* \param olen length of the output data, will be filled 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.
* \param tag buffer holding the authentication tag * \param tag The buffer holding the authentication tag.
* \param tag_len length of the authentication tag * \param tag_len The length of the authentication tag.
* *
* \returns 0 on success, or * \returns \c 0 on success, or
* MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
* MBEDTLS_ERR_CIPHER_AUTH_FAILED if data isn't authentic, * #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic,
* or a cipher specific error code. * or a cipher-specific error code on failure for any other reason.
* *
* \note If the data is not authentic, then the output buffer * \note If the data is not authentic, then the output buffer
* is zeroed out to prevent the unauthentic plaintext to * is zeroed out to prevent the unauthentic plaintext being
* be used by mistake, making this interface safer. * 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,
......
...@@ -4,7 +4,8 @@ ...@@ -4,7 +4,8 @@
* \brief Cipher wrappers. * \brief Cipher wrappers.
* *
* \author Adriaan de Jong <dejong@fox-it.com> * \author Adriaan de Jong <dejong@fox-it.com>
* */
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
......
/** /**
* \file cmac.h * \file cmac.h
* *
* \brief Cipher-based Message Authentication Code (CMAC) Mode for * \brief The Cipher-based Message Authentication Code (CMAC) Mode for
* Authentication * Authentication.
* */
* Copyright (C) 2015-2016, ARM Limited, All Rights Reserved /*
* Copyright (C) 2015-2018, Arm Limited (or its affiliates), All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
* Licensed under the Apache License, Version 2.0 (the "License"); you may * Licensed under the Apache License, Version 2.0 (the "License"); you may
...@@ -19,8 +20,9 @@ ...@@ -19,8 +20,9 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
* *
* This file is part of mbed TLS (https://tls.mbed.org) * This file is part of Mbed TLS (https://tls.mbed.org)
*/ */
#ifndef MBEDTLS_CMAC_H #ifndef MBEDTLS_CMAC_H
#define MBEDTLS_CMAC_H #define MBEDTLS_CMAC_H
...@@ -30,106 +32,125 @@ ...@@ -30,106 +32,125 @@
extern "C" { extern "C" {
#endif #endif
#define MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED -0x007A /**< CMAC hardware accelerator failed. */
#define MBEDTLS_AES_BLOCK_SIZE 16 #define MBEDTLS_AES_BLOCK_SIZE 16
#define MBEDTLS_DES3_BLOCK_SIZE 8 #define MBEDTLS_DES3_BLOCK_SIZE 8
#if defined(MBEDTLS_AES_C) #if defined(MBEDTLS_AES_C)
#define MBEDTLS_CIPHER_BLKSIZE_MAX 16 /* longest used by CMAC is AES */ #define MBEDTLS_CIPHER_BLKSIZE_MAX 16 /* The longest block used by CMAC is that of AES. */
#else #else
#define MBEDTLS_CIPHER_BLKSIZE_MAX 8 /* longest used by CMAC is 3DES */ #define MBEDTLS_CIPHER_BLKSIZE_MAX 8 /* The longest block used by CMAC is that of 3DES. */
#endif #endif
#if !defined(MBEDTLS_CMAC_ALT)
/** /**
* CMAC context structure - Contains internal state information only * The CMAC context structure.
*/ */
struct mbedtls_cmac_context_t struct mbedtls_cmac_context_t
{ {
/** Internal state of the CMAC algorithm */ /** The internal state of the CMAC algorithm. */
unsigned char state[MBEDTLS_CIPHER_BLKSIZE_MAX]; unsigned char state[MBEDTLS_CIPHER_BLKSIZE_MAX];
/** Unprocessed data - either data that was not block aligned and is still /** Unprocessed data - either data that was not block aligned and is still
* pending to be processed, or the final block */ * pending processing, or the final block. */
unsigned char unprocessed_block[MBEDTLS_CIPHER_BLKSIZE_MAX]; unsigned char unprocessed_block[MBEDTLS_CIPHER_BLKSIZE_MAX];
/** Length of data pending to be processed */ /** The length of data pending processing. */
size_t unprocessed_len; size_t unprocessed_len;
}; };
/** /**
* \brief Set the CMAC key and prepare to authenticate the input * \brief This function sets the CMAC key, and prepares to authenticate
* data. * the input data.
* Should be called with an initialized cipher context. * Must be called with an initialized cipher context.
* *
* \param ctx Cipher context. This should be a cipher context, * \param ctx The cipher context used for the CMAC operation, initialized
* initialized to be one of the following types: * as one of the following types:<ul>
* MBEDTLS_CIPHER_AES_128_ECB, MBEDTLS_CIPHER_AES_192_ECB, * <li>MBEDTLS_CIPHER_AES_128_ECB</li>
* MBEDTLS_CIPHER_AES_256_ECB or * <li>MBEDTLS_CIPHER_AES_192_ECB</li>
* MBEDTLS_CIPHER_DES_EDE3_ECB. * <li>MBEDTLS_CIPHER_AES_256_ECB</li>
* \param key CMAC key * <li>MBEDTLS_CIPHER_DES_EDE3_ECB</li></ul>
* \param keybits length of the CMAC key in bits * \param key The CMAC key.
* (must be acceptable by the cipher) * \param keybits The length of the CMAC key in bits.
* * Must be supported by the cipher.
* \return 0 if successful, or a cipher specific error code *
* \return \c 0 on success, or a cipher-specific error code.
*/ */
int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx, int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx,
const unsigned char *key, size_t keybits ); const unsigned char *key, size_t keybits );
/** /**
* \brief Generic CMAC process buffer. * \brief This function feeds an input buffer into an ongoing CMAC
* Called between mbedtls_cipher_cmac_starts() or * computation.
* mbedtls_cipher_cmac_reset() and *
* mbedtls_cipher_cmac_finish(). * It is called between mbedtls_cipher_cmac_starts() or
* May be called repeatedly. * mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish().
* * Can be called repeatedly.
* \param ctx CMAC context *
* \param input buffer holding the data * \param ctx The cipher context used for the CMAC operation.
* \param ilen length of the input data * \param input The buffer holding the input data.
* * \param ilen The length of the input data.
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter *
* verification fails. * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
* if parameter verification fails.
*/ */
int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx, int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx,
const unsigned char *input, size_t ilen ); const unsigned char *input, size_t ilen );
/** /**
* \brief Output CMAC. * \brief This function finishes the CMAC operation, and writes
* Called after mbedtls_cipher_cmac_update(). * the result to the output buffer.
* Usually followed by mbedtls_cipher_cmac_reset(), then *
* mbedtls_cipher_cmac_starts(), or mbedtls_cipher_free(). * It is called after mbedtls_cipher_cmac_update().
* It can be followed by mbedtls_cipher_cmac_reset() and
* mbedtls_cipher_cmac_update(), or mbedtls_cipher_free().
* *
* \param ctx CMAC context * \param ctx The cipher context used for the CMAC operation.
* \param output Generic CMAC checksum result * \param output The output buffer for the CMAC checksum result.
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
* verification fails. * if parameter verification fails.
*/ */
int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx, int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx,
unsigned char *output ); unsigned char *output );
/** /**
* \brief Prepare to authenticate a new message with the same key. * \brief This function prepares the authentication of another
* Called after mbedtls_cipher_cmac_finish() and before * message with the same key as the previous CMAC
* mbedtls_cipher_cmac_update(). * operation.
* *
* \param ctx CMAC context to be reset * It is called after mbedtls_cipher_cmac_finish()
* and before mbedtls_cipher_cmac_update().
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The cipher context used for the CMAC operation.
* verification fails. *
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
* if parameter verification fails.
*/ */
int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx ); int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx );
/** /**
* \brief Output = Generic_CMAC( cmac key, input buffer ) * \brief This function calculates the full generic CMAC
* on the input buffer with the provided key.
*
* The function allocates the context, performs the
* calculation, and frees the context.
*
* The CMAC result is calculated as
* output = generic CMAC(cmac key, input buffer).
* *
* \param cipher_info message digest info
* \param key CMAC key
* \param keylen length of the CMAC key in bits
* \param input buffer holding the data
* \param ilen length of the input data
* \param output Generic CMAC-result
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param cipher_info The cipher information.
* verification fails. * \param key The CMAC key.
* \param keylen The length of the CMAC key in bits.
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
* \param output The buffer for the generic CMAC result.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
* if parameter verification fails.
*/ */
int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info, int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info,
const unsigned char *key, size_t keylen, const unsigned char *key, size_t keylen,
...@@ -138,27 +159,44 @@ int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info, ...@@ -138,27 +159,44 @@ int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info,
#if defined(MBEDTLS_AES_C) #if defined(MBEDTLS_AES_C)
/** /**
* \brief AES-CMAC-128-PRF * \brief This function implements the AES-CMAC-PRF-128 pseudorandom
* Implementation of (AES-CMAC-PRF-128), as defined in RFC 4615 * function, as defined in
* * <em>RFC-4615: The Advanced Encryption Standard-Cipher-based
* \param key PRF key * Message Authentication Code-Pseudo-Random Function-128
* \param key_len PRF key length in bytes * (AES-CMAC-PRF-128) Algorithm for the Internet Key
* \param input buffer holding the input data * Exchange Protocol (IKE).</em>
* \param in_len length of the input data in bytes *
* \param output buffer holding the generated pseudorandom output (16 bytes) * \param key The key to use.
* * \param key_len The key length in Bytes.
* \return 0 if successful * \param input The buffer holding the input data.
* \param in_len The length of the input data in Bytes.
* \param output The buffer holding the generated 16 Bytes of
* pseudorandom output.
*
* \return \c 0 on success.
*/ */
int mbedtls_aes_cmac_prf_128( const unsigned char *key, size_t key_len, int mbedtls_aes_cmac_prf_128( const unsigned char *key, size_t key_len,
const unsigned char *input, size_t in_len, const unsigned char *input, size_t in_len,
unsigned char output[16] ); unsigned char output[16] );
#endif /* MBEDTLS_AES_C */ #endif /* MBEDTLS_AES_C */
#ifdef __cplusplus
}
#endif
#else /* !MBEDTLS_CMAC_ALT */
#include "cmac_alt.h"
#endif /* !MBEDTLS_CMAC_ALT */
#ifdef __cplusplus
extern "C" {
#endif
#if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) ) #if defined(MBEDTLS_SELF_TEST) && ( defined(MBEDTLS_AES_C) || defined(MBEDTLS_DES_C) )
/** /**
* \brief Checkup routine * \brief The CMAC checkup routine.
* *
* \return 0 if successful, or 1 if the test failed * \return \c 0 on success, or \c 1 on failure.
*/ */
int mbedtls_cmac_self_test( int verbose ); int mbedtls_cmac_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */ #endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */
......
...@@ -5,7 +5,8 @@ ...@@ -5,7 +5,8 @@
* for the PolarSSL naming conventions. * for the PolarSSL naming conventions.
* *
* \deprecated Use the new names directly instead * \deprecated Use the new names directly instead
* */
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
......
...@@ -6,7 +6,8 @@ ...@@ -6,7 +6,8 @@
* This set of compile-time options may be used to enable * This set of compile-time options may be used to enable
* or disable features selectively, and reduce the global * or disable features selectively, and reduce the global
* memory footprint. * memory footprint.
* */
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
...@@ -261,20 +262,32 @@ ...@@ -261,20 +262,32 @@
* *
* Uncomment a macro to enable alternate implementation of the corresponding * Uncomment a macro to enable alternate implementation of the corresponding
* module. * module.
*
* \warning MD2, MD4, MD5, ARC4, DES and SHA-1 are considered weak and their
* use constitutes a security risk. If possible, we recommend
* avoiding dependencies on them, and considering stronger message
* digests and ciphers instead.
*
*/ */
//#define MBEDTLS_AES_ALT //#define MBEDTLS_AES_ALT
//#define MBEDTLS_ARC4_ALT //#define MBEDTLS_ARC4_ALT
//#define MBEDTLS_BLOWFISH_ALT //#define MBEDTLS_BLOWFISH_ALT
//#define MBEDTLS_CAMELLIA_ALT //#define MBEDTLS_CAMELLIA_ALT
//#define MBEDTLS_CCM_ALT
//#define MBEDTLS_CMAC_ALT
//#define MBEDTLS_DES_ALT //#define MBEDTLS_DES_ALT
//#define MBEDTLS_XTEA_ALT //#define MBEDTLS_DHM_ALT
//#define MBEDTLS_ECJPAKE_ALT
//#define MBEDTLS_GCM_ALT
//#define MBEDTLS_MD2_ALT //#define MBEDTLS_MD2_ALT
//#define MBEDTLS_MD4_ALT //#define MBEDTLS_MD4_ALT
//#define MBEDTLS_MD5_ALT //#define MBEDTLS_MD5_ALT
//#define MBEDTLS_RIPEMD160_ALT //#define MBEDTLS_RIPEMD160_ALT
//#define MBEDTLS_RSA_ALT
//#define MBEDTLS_SHA1_ALT //#define MBEDTLS_SHA1_ALT
//#define MBEDTLS_SHA256_ALT //#define MBEDTLS_SHA256_ALT
//#define MBEDTLS_SHA512_ALT //#define MBEDTLS_SHA512_ALT
//#define MBEDTLS_XTEA_ALT
/* /*
* When replacing the elliptic curve module, pleace consider, that it is * When replacing the elliptic curve module, pleace consider, that it is
* implemented with two .c files: * implemented with two .c files:
...@@ -314,6 +327,12 @@ ...@@ -314,6 +327,12 @@
* *
* Uncomment a macro to enable alternate implementation of the corresponding * Uncomment a macro to enable alternate implementation of the corresponding
* function. * function.
*
* \warning MD2, MD4, MD5, DES and SHA-1 are considered weak and their use
* constitutes a security risk. If possible, we recommend avoiding
* dependencies on them, and considering stronger message digests
* and ciphers instead.
*
*/ */
//#define MBEDTLS_MD2_PROCESS_ALT //#define MBEDTLS_MD2_PROCESS_ALT
//#define MBEDTLS_MD4_PROCESS_ALT //#define MBEDTLS_MD4_PROCESS_ALT
...@@ -329,6 +348,11 @@ ...@@ -329,6 +348,11 @@
//#define MBEDTLS_AES_SETKEY_DEC_ALT //#define MBEDTLS_AES_SETKEY_DEC_ALT
//#define MBEDTLS_AES_ENCRYPT_ALT //#define MBEDTLS_AES_ENCRYPT_ALT
//#define MBEDTLS_AES_DECRYPT_ALT //#define MBEDTLS_AES_DECRYPT_ALT
//#define MBEDTLS_ECDH_GEN_PUBLIC_ALT
//#define MBEDTLS_ECDH_COMPUTE_SHARED_ALT
//#define MBEDTLS_ECDSA_VERIFY_ALT
//#define MBEDTLS_ECDSA_SIGN_ALT
//#define MBEDTLS_ECDSA_GENKEY_ALT
/** /**
* \def MBEDTLS_ECP_INTERNAL_ALT * \def MBEDTLS_ECP_INTERNAL_ALT
...@@ -513,6 +537,9 @@ ...@@ -513,6 +537,9 @@
* MBEDTLS_TLS_DHE_RSA_WITH_DES_CBC_SHA * MBEDTLS_TLS_DHE_RSA_WITH_DES_CBC_SHA
* *
* Uncomment this macro to enable weak ciphersuites * Uncomment this macro to enable weak ciphersuites
*
* \warning DES is considered a weak cipher and its use constitutes a
* security risk. We recommend considering stronger ciphers instead.
*/ */
//#define MBEDTLS_ENABLE_WEAK_CIPHERSUITES //#define MBEDTLS_ENABLE_WEAK_CIPHERSUITES
...@@ -618,6 +645,13 @@ ...@@ -618,6 +645,13 @@
* MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 * MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256
* MBEDTLS_TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA * MBEDTLS_TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA
* MBEDTLS_TLS_DHE_PSK_WITH_RC4_128_SHA * MBEDTLS_TLS_DHE_PSK_WITH_RC4_128_SHA
*
* \warning Using DHE constitutes a security risk as it
* is not possible to validate custom DH parameters.
* If possible, it is recommended users should consider
* preferring other methods of key exchange.
* See dhm.h for more details.
*
*/ */
#define MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED #define MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED
...@@ -717,6 +751,13 @@ ...@@ -717,6 +751,13 @@
* MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 * MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256
* MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA * MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA
* MBEDTLS_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA * MBEDTLS_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
*
* \warning Using DHE constitutes a security risk as it
* is not possible to validate custom DH parameters.
* If possible, it is recommended users should consider
* preferring other methods of key exchange.
* See dhm.h for more details.
*
*/ */
#define MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED #define MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED
...@@ -1155,6 +1196,13 @@ ...@@ -1155,6 +1196,13 @@
* misuse/misunderstand. * misuse/misunderstand.
* *
* Comment this to disable support for renegotiation. * Comment this to disable support for renegotiation.
*
* \note Even if this option is disabled, both client and server are aware
* of the Renegotiation Indication Extension (RFC 5746) used to
* prevent the SSL renegotiation attack (see RFC 5746 Sect. 1).
* (See \c mbedtls_ssl_conf_legacy_renegotiation for the
* configuration of this extension).
*
*/ */
#define MBEDTLS_SSL_RENEGOTIATION #define MBEDTLS_SSL_RENEGOTIATION
...@@ -1596,6 +1644,11 @@ ...@@ -1596,6 +1644,11 @@
* MBEDTLS_TLS_RSA_WITH_RC4_128_MD5 * MBEDTLS_TLS_RSA_WITH_RC4_128_MD5
* MBEDTLS_TLS_RSA_PSK_WITH_RC4_128_SHA * MBEDTLS_TLS_RSA_PSK_WITH_RC4_128_SHA
* MBEDTLS_TLS_PSK_WITH_RC4_128_SHA * MBEDTLS_TLS_PSK_WITH_RC4_128_SHA
*
* \warning ARC4 is considered a weak cipher and its use constitutes a
* security risk. If possible, we recommend avoidng dependencies on
* it, and considering stronger ciphers instead.
*
*/ */
#define MBEDTLS_ARC4_C #define MBEDTLS_ARC4_C
...@@ -1649,6 +1702,7 @@ ...@@ -1649,6 +1702,7 @@
* library/ecp.c * library/ecp.c
* library/ecdsa.c * library/ecdsa.c
* library/rsa.c * library/rsa.c
* library/rsa_internal.c
* library/ssl_tls.c * library/ssl_tls.c
* *
* This module is required for RSA, DHM and ECC (ECDH, ECDSA) support. * This module is required for RSA, DHM and ECC (ECDH, ECDSA) support.
...@@ -1821,6 +1875,9 @@ ...@@ -1821,6 +1875,9 @@
* MBEDTLS_TLS_PSK_WITH_3DES_EDE_CBC_SHA * MBEDTLS_TLS_PSK_WITH_3DES_EDE_CBC_SHA
* *
* PEM_PARSE uses DES/3DES for decrypting encrypted keys. * PEM_PARSE uses DES/3DES for decrypting encrypted keys.
*
* \warning DES is considered a weak cipher and its use constitutes a
* security risk. We recommend considering stronger ciphers instead.
*/ */
#define MBEDTLS_DES_C #define MBEDTLS_DES_C
...@@ -1835,6 +1892,13 @@ ...@@ -1835,6 +1892,13 @@
* *
* This module is used by the following key exchanges: * This module is used by the following key exchanges:
* DHE-RSA, DHE-PSK * DHE-RSA, DHE-PSK
*
* \warning Using DHE constitutes a security risk as it
* is not possible to validate custom DH parameters.
* If possible, it is recommended users should consider
* preferring other methods of key exchange.
* See dhm.h for more details.
*
*/ */
#define MBEDTLS_DHM_C #define MBEDTLS_DHM_C
...@@ -2000,6 +2064,11 @@ ...@@ -2000,6 +2064,11 @@
* Caller: * Caller:
* *
* Uncomment to enable support for (rare) MD2-signed X.509 certs. * Uncomment to enable support for (rare) MD2-signed X.509 certs.
*
* \warning MD2 is considered a weak message digest and its use constitutes a
* security risk. If possible, we recommend avoiding dependencies on
* it, and considering stronger message digests instead.
*
*/ */
//#define MBEDTLS_MD2_C //#define MBEDTLS_MD2_C
...@@ -2012,6 +2081,11 @@ ...@@ -2012,6 +2081,11 @@
* Caller: * Caller:
* *
* Uncomment to enable support for (rare) MD4-signed X.509 certs. * Uncomment to enable support for (rare) MD4-signed X.509 certs.
*
* \warning MD4 is considered a weak message digest and its use constitutes a
* security risk. If possible, we recommend avoiding dependencies on
* it, and considering stronger message digests instead.
*
*/ */
//#define MBEDTLS_MD4_C //#define MBEDTLS_MD4_C
...@@ -2025,8 +2099,15 @@ ...@@ -2025,8 +2099,15 @@
* library/pem.c * library/pem.c
* library/ssl_tls.c * library/ssl_tls.c
* *
* This module is required for SSL/TLS and X.509. * This module is required for SSL/TLS up to version 1.1, and for TLS 1.2
* PEM_PARSE uses MD5 for decrypting encrypted keys. * depending on the handshake parameters. Further, it is used for checking
* MD5-signed certificates, and for PBKDF1 when decrypting PEM-encoded
* encrypted keys.
*
* \warning MD5 is considered a weak message digest and its use constitutes a
* security risk. If possible, we recommend avoiding dependencies on
* it, and considering stronger message digests instead.
*
*/ */
#define MBEDTLS_MD5_C #define MBEDTLS_MD5_C
...@@ -2262,6 +2343,7 @@ ...@@ -2262,6 +2343,7 @@
* Enable the RSA public-key cryptosystem. * Enable the RSA public-key cryptosystem.
* *
* Module: library/rsa.c * Module: library/rsa.c
* library/rsa_internal.c
* Caller: library/ssl_cli.c * Caller: library/ssl_cli.c
* library/ssl_srv.c * library/ssl_srv.c
* library/ssl_tls.c * library/ssl_tls.c
...@@ -2288,6 +2370,11 @@ ...@@ -2288,6 +2370,11 @@
* *
* This module is required for SSL/TLS up to version 1.1, for TLS 1.2 * This module is required for SSL/TLS up to version 1.1, for TLS 1.2
* depending on the handshake parameters, and for SHA1-signed certificates. * depending on the handshake parameters, and for SHA1-signed certificates.
*
* \warning SHA-1 is considered a weak message digest and its use constitutes
* a security risk. If possible, we recommend avoiding dependencies
* on it, and considering stronger message digests instead.
*
*/ */
#define MBEDTLS_SHA1_C #define MBEDTLS_SHA1_C
...@@ -2676,8 +2763,13 @@ ...@@ -2676,8 +2763,13 @@
* Allow SHA-1 in the default TLS configuration for certificate signing. * Allow SHA-1 in the default TLS configuration for certificate signing.
* Without this build-time option, SHA-1 support must be activated explicitly * Without this build-time option, SHA-1 support must be activated explicitly
* through mbedtls_ssl_conf_cert_profile. Turning on this option is not * through mbedtls_ssl_conf_cert_profile. Turning on this option is not
* recommended because of it is possible to generte SHA-1 collisions, however * recommended because of it is possible to generate SHA-1 collisions, however
* this may be safe for legacy infrastructure where additional controls apply. * this may be safe for legacy infrastructure where additional controls apply.
*
* \warning SHA-1 is considered a weak message digest and its use constitutes
* a security risk. If possible, we recommend avoiding dependencies
* on it, and considering stronger message digests instead.
*
*/ */
// #define MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES // #define MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES
...@@ -2688,7 +2780,13 @@ ...@@ -2688,7 +2780,13 @@
* The use of SHA-1 in TLS <= 1.1 and in HMAC-SHA-1 is always allowed by * The use of SHA-1 in TLS <= 1.1 and in HMAC-SHA-1 is always allowed by
* default. At the time of writing, there is no practical attack on the use * default. At the time of writing, there is no practical attack on the use
* of SHA-1 in handshake signatures, hence this option is turned on by default * of SHA-1 in handshake signatures, hence this option is turned on by default
* for compatibility with existing peers. * to preserve compatibility with existing peers, but the general
* warning applies nonetheless:
*
* \warning SHA-1 is considered a weak message digest and its use constitutes
* a security risk. If possible, we recommend avoiding dependencies
* on it, and considering stronger message digests instead.
*
*/ */
#define MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE #define MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE
......
/** /**
* \file ctr_drbg.h * \file ctr_drbg.h
* *
* \brief CTR_DRBG based on AES-256 (NIST SP 800-90) * \brief CTR_DRBG is based on AES-256, as defined in <em>NIST SP 800-90A:
* Recommendation for Random Number Generation Using Deterministic
* Random Bit Generators</em>.
* *
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved */
/*
* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
* Licensed under the Apache License, Version 2.0 (the "License"); you may * Licensed under the Apache License, Version 2.0 (the "License"); you may
...@@ -18,8 +22,9 @@ ...@@ -18,8 +22,9 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
* *
* This file is part of mbed TLS (https://tls.mbed.org) * This file is part of Mbed TLS (https://tls.mbed.org)
*/ */
#ifndef MBEDTLS_CTR_DRBG_H #ifndef MBEDTLS_CTR_DRBG_H
#define MBEDTLS_CTR_DRBG_H #define MBEDTLS_CTR_DRBG_H
...@@ -30,78 +35,95 @@ ...@@ -30,78 +35,95 @@
#endif #endif
#define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034 /**< The entropy source failed. */ #define MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED -0x0034 /**< The entropy source failed. */
#define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036 /**< Too many random requested in single call. */ #define MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG -0x0036 /**< The requested random buffer length is too big. */
#define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038 /**< Input too large (Entropy + additional). */ #define MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG -0x0038 /**< The input (entropy + additional data) is too large. */
#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read/write error in file. */ #define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read or write error in file. */
#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< Block size used by the cipher */ #define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< The block size used by the cipher. */
#define MBEDTLS_CTR_DRBG_KEYSIZE 32 /**< Key size used by the cipher */ #define MBEDTLS_CTR_DRBG_KEYSIZE 32 /**< The key size used by the cipher. */
#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) #define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) /**< The key size for the DRBG operation, in bits. */
#define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) #define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) /**< The seed length, calculated as (counter + AES key). */
/**< The seed length (counter + AES key) */
/** /**
* \name SECTION: Module settings * \name SECTION: Module settings
* *
* The configuration options you can set for this module are in this section. * The configuration options you can set for this module are in this section.
* Either change them in config.h or define them on the compiler command line. * Either change them in config.h or define them using the compiler command
* line.
* \{ * \{
*/ */
#if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN) #if !defined(MBEDTLS_CTR_DRBG_ENTROPY_LEN)
#if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256) #if defined(MBEDTLS_SHA512_C) && !defined(MBEDTLS_ENTROPY_FORCE_SHA256)
#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48 /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */ #define MBEDTLS_CTR_DRBG_ENTROPY_LEN 48
/**< The amount of entropy used per seed by default:
* <ul><li>48 with SHA-512.</li>
* <li>32 with SHA-256.</li></ul>
*/
#else #else
#define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32 /**< Amount of entropy used per seed by default (48 with SHA-512, 32 with SHA-256) */ #define MBEDTLS_CTR_DRBG_ENTROPY_LEN 32
/**< Amount of entropy used per seed by default:
* <ul><li>48 with SHA-512.</li>
* <li>32 with SHA-256.</li></ul>
*/
#endif #endif
#endif #endif
#if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL) #if !defined(MBEDTLS_CTR_DRBG_RESEED_INTERVAL)
#define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000 /**< Interval before reseed is performed by default */ #define MBEDTLS_CTR_DRBG_RESEED_INTERVAL 10000
/**< The interval before reseed is performed by default. */
#endif #endif
#if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT) #if !defined(MBEDTLS_CTR_DRBG_MAX_INPUT)
#define MBEDTLS_CTR_DRBG_MAX_INPUT 256 /**< Maximum number of additional input bytes */ #define MBEDTLS_CTR_DRBG_MAX_INPUT 256
/**< The maximum number of additional input Bytes. */
#endif #endif
#if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST) #if !defined(MBEDTLS_CTR_DRBG_MAX_REQUEST)
#define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024 /**< Maximum number of requested bytes per call */ #define MBEDTLS_CTR_DRBG_MAX_REQUEST 1024
/**< The maximum number of requested Bytes per call. */
#endif #endif
#if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT) #if !defined(MBEDTLS_CTR_DRBG_MAX_SEED_INPUT)
#define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384 /**< Maximum size of (re)seed buffer */ #define MBEDTLS_CTR_DRBG_MAX_SEED_INPUT 384
/**< The maximum size of seed or reseed buffer. */
#endif #endif
/* \} name SECTION: Module settings */ /* \} name SECTION: Module settings */
#define MBEDTLS_CTR_DRBG_PR_OFF 0 /**< No prediction resistance */ #define MBEDTLS_CTR_DRBG_PR_OFF 0
#define MBEDTLS_CTR_DRBG_PR_ON 1 /**< Prediction resistance enabled */ /**< Prediction resistance is disabled. */
#define MBEDTLS_CTR_DRBG_PR_ON 1
/**< Prediction resistance is enabled. */
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
/** /**
* \brief CTR_DRBG context structure * \brief The CTR_DRBG context structure.
*/ */
typedef struct typedef struct
{ {
unsigned char counter[16]; /*!< counter (V) */ unsigned char counter[16]; /*!< The counter (V). */
int reseed_counter; /*!< reseed counter */ int reseed_counter; /*!< The reseed counter. */
int prediction_resistance; /*!< enable prediction resistance (Automatic int prediction_resistance; /*!< This determines whether prediction
reseed before every random generation) */ resistance is enabled, that is
size_t entropy_len; /*!< amount of entropy grabbed on each whether to systematically reseed before
(re)seed */ each random generation. */
int reseed_interval; /*!< reseed interval */ size_t entropy_len; /*!< The amount of entropy grabbed on each
seed or reseed operation. */
mbedtls_aes_context aes_ctx; /*!< AES context */ int reseed_interval; /*!< The reseed interval. */
mbedtls_aes_context aes_ctx; /*!< The AES context. */
/* /*
* Callbacks (Entropy) * Callbacks (Entropy)
*/ */
int (*f_entropy)(void *, unsigned char *, size_t); int (*f_entropy)(void *, unsigned char *, size_t);
/*!< The entropy callback function. */
void *p_entropy; /*!< context for the entropy function */ void *p_entropy; /*!< The context for the entropy function. */
#if defined(MBEDTLS_THREADING_C) #if defined(MBEDTLS_THREADING_C)
mbedtls_threading_mutex_t mutex; mbedtls_threading_mutex_t mutex;
...@@ -110,31 +132,32 @@ typedef struct ...@@ -110,31 +132,32 @@ typedef struct
mbedtls_ctr_drbg_context; mbedtls_ctr_drbg_context;
/** /**
* \brief CTR_DRBG context initialization * \brief This function initializes the CTR_DRBG context,
* Makes the context ready for mbedtls_ctr_drbg_seed() or * and prepares it for mbedtls_ctr_drbg_seed()
* mbedtls_ctr_drbg_free(). * or mbedtls_ctr_drbg_free().
* *
* \param ctx CTR_DRBG context to be initialized * \param ctx The CTR_DRBG context to initialize.
*/ */
void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx ); void mbedtls_ctr_drbg_init( mbedtls_ctr_drbg_context *ctx );
/** /**
* \brief CTR_DRBG initial seeding * \brief This function seeds and sets up the CTR_DRBG
* Seed and setup entropy source for future reseeds. * entropy source for future reseeds.
* *
* Note: Personalization data can be provided in addition to the more generic * \note Personalization data can be provided in addition to the more generic
* entropy source to make this instantiation as unique as possible. * entropy source, to make this instantiation as unique as possible.
* *
* \param ctx CTR_DRBG context to be seeded * \param ctx The CTR_DRBG context to seed.
* \param f_entropy Entropy callback (p_entropy, buffer to fill, buffer * \param f_entropy The entropy callback, taking as arguments the
* length) * \p p_entropy context, the buffer to fill, and the
* \param p_entropy Entropy context length of the buffer.
* \param custom Personalization data (Device specific identifiers) * \param p_entropy The entropy context.
* (Can be NULL) * \param custom Personalization data, that is device-specific
* \param len Length of personalization data identifiers. Can be NULL.
* \param len The length of the personalization data.
* *
* \return 0 if successful, or * \return \c 0 on success, or
* MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
*/ */
int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx, int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
int (*f_entropy)(void *, unsigned char *, size_t), int (*f_entropy)(void *, unsigned char *, size_t),
...@@ -143,138 +166,147 @@ int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx, ...@@ -143,138 +166,147 @@ int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx,
size_t len ); size_t len );
/** /**
* \brief Clear CTR_CRBG context data * \brief This function clears CTR_CRBG context data.
* *
* \param ctx CTR_DRBG context to clear * \param ctx The CTR_DRBG context to clear.
*/ */
void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx ); void mbedtls_ctr_drbg_free( mbedtls_ctr_drbg_context *ctx );
/** /**
* \brief Enable / disable prediction resistance (Default: Off) * \brief This function turns prediction resistance on or off.
* The default value is off.
* *
* Note: If enabled, entropy is used for ctx->entropy_len before each call! * \note If enabled, entropy is gathered at the beginning of
* Only use this if you have ample supply of good entropy! * every call to mbedtls_ctr_drbg_random_with_add().
* Only use this if your entropy source has sufficient
* throughput.
* *
* \param ctx CTR_DRBG context * \param ctx The CTR_DRBG context.
* \param resistance MBEDTLS_CTR_DRBG_PR_ON or MBEDTLS_CTR_DRBG_PR_OFF * \param resistance #MBEDTLS_CTR_DRBG_PR_ON or #MBEDTLS_CTR_DRBG_PR_OFF.
*/ */
void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx, void mbedtls_ctr_drbg_set_prediction_resistance( mbedtls_ctr_drbg_context *ctx,
int resistance ); int resistance );
/** /**
* \brief Set the amount of entropy grabbed on each (re)seed * \brief This function sets the amount of entropy grabbed on each
* (Default: MBEDTLS_CTR_DRBG_ENTROPY_LEN) * seed or reseed. The default value is
* #MBEDTLS_CTR_DRBG_ENTROPY_LEN.
* *
* \param ctx CTR_DRBG context * \param ctx The CTR_DRBG context.
* \param len Amount of entropy to grab * \param len The amount of entropy to grab.
*/ */
void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx, void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx,
size_t len ); size_t len );
/** /**
* \brief Set the reseed interval * \brief This function sets the reseed interval.
* (Default: MBEDTLS_CTR_DRBG_RESEED_INTERVAL) * The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL.
* *
* \param ctx CTR_DRBG context * \param ctx The CTR_DRBG context.
* \param interval Reseed interval * \param interval The reseed interval.
*/ */
void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx, void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx,
int interval ); int interval );
/** /**
* \brief CTR_DRBG reseeding (extracts data from entropy source) * \brief This function reseeds the CTR_DRBG context, that is
* extracts data from the entropy source.
* *
* \param ctx CTR_DRBG context * \param ctx The CTR_DRBG context.
* \param additional Additional data to add to state (Can be NULL) * \param additional Additional data to add to the state. Can be NULL.
* \param len Length of additional data * \param len The length of the additional data.
* *
* \return 0 if successful, or * \return \c 0 on success, or
* MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure.
*/ */
int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx, int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx,
const unsigned char *additional, size_t len ); const unsigned char *additional, size_t len );
/** /**
* \brief CTR_DRBG update state * \brief This function updates the state of the CTR_DRBG context.
* *
* \param ctx CTR_DRBG context * \param ctx The CTR_DRBG context.
* \param additional Additional data to update state with * \param additional The data to update the state with.
* \param add_len Length of additional data * \param add_len Length of \p additional data.
* *
* \note If add_len is greater than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, * \note If \p add_len is greater than #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT,
* only the first MBEDTLS_CTR_DRBG_MAX_SEED_INPUT bytes are used, * only the first #MBEDTLS_CTR_DRBG_MAX_SEED_INPUT Bytes are used.
* the remaining ones are silently discarded. * The remaining Bytes are silently discarded.
*/ */
void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx, void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx,
const unsigned char *additional, size_t add_len ); const unsigned char *additional, size_t add_len );
/** /**
* \brief CTR_DRBG generate random with additional update input * \brief This function updates a CTR_DRBG instance with additional
* data and uses it to generate random data.
* *
* Note: Automatically reseeds if reseed_counter is reached. * \note The function automatically reseeds if the reseed counter is exceeded.
* *
* \param p_rng CTR_DRBG context * \param p_rng The CTR_DRBG context. This must be a pointer to a
* \param output Buffer to fill * #mbedtls_ctr_drbg_context structure.
* \param output_len Length of the buffer * \param output The buffer to fill.
* \param additional Additional data to update with (Can be NULL) * \param output_len The length of the buffer.
* \param add_len Length of additional data * \param additional Additional data to update. Can be NULL.
* \param add_len The length of the additional data.
* *
* \return 0 if successful, or * \return \c 0 on success, or
* MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
* MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
*/ */
int mbedtls_ctr_drbg_random_with_add( void *p_rng, int mbedtls_ctr_drbg_random_with_add( void *p_rng,
unsigned char *output, size_t output_len, unsigned char *output, size_t output_len,
const unsigned char *additional, size_t add_len ); const unsigned char *additional, size_t add_len );
/** /**
* \brief CTR_DRBG generate random * \brief This function uses CTR_DRBG to generate random data.
* *
* Note: Automatically reseeds if reseed_counter is reached. * \note The function automatically reseeds if the reseed counter is exceeded.
* *
* \param p_rng CTR_DRBG context * \param p_rng The CTR_DRBG context. This must be a pointer to a
* \param output Buffer to fill * #mbedtls_ctr_drbg_context structure.
* \param output_len Length of the buffer * \param output The buffer to fill.
* \param output_len The length of the buffer.
* *
* \return 0 if successful, or * \return \c 0 on success, or
* MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
* MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure.
*/ */
int mbedtls_ctr_drbg_random( void *p_rng, int mbedtls_ctr_drbg_random( void *p_rng,
unsigned char *output, size_t output_len ); unsigned char *output, size_t output_len );
#if defined(MBEDTLS_FS_IO) #if defined(MBEDTLS_FS_IO)
/** /**
* \brief Write a seed file * \brief This function writes a seed file.
* *
* \param ctx CTR_DRBG context * \param ctx The CTR_DRBG context.
* \param path Name of the file * \param path The name of the file.
* *
* \return 0 if successful, * \return \c 0 on success,
* MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or * #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or
* MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on
* failure.
*/ */
int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path ); int mbedtls_ctr_drbg_write_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
/** /**
* \brief Read and update a seed file. Seed is added to this * \brief This function reads and updates a seed file. The seed
* instance * is added to this instance.
* *
* \param ctx CTR_DRBG context * \param ctx The CTR_DRBG context.
* \param path Name of the file * \param path The name of the file.
* *
* \return 0 if successful, * \return \c 0 on success,
* MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, * #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error,
* MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or
* MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG * #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure.
*/ */
int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path ); int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path );
#endif /* MBEDTLS_FS_IO */ #endif /* MBEDTLS_FS_IO */
/** /**
* \brief Checkup routine * \brief The CTR_DRBG checkup routine.
* *
* \return 0 if successful, or 1 if the test failed * \return \c 0 on success, or \c 1 on failure.
*/ */
int mbedtls_ctr_drbg_self_test( int verbose ); int mbedtls_ctr_drbg_self_test( int verbose );
......
...@@ -2,7 +2,8 @@ ...@@ -2,7 +2,8 @@
* \file debug.h * \file debug.h
* *
* \brief Functions for controlling and providing debug output from the library. * \brief Functions for controlling and providing debug output from the library.
* */
/*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment