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

Merge branch 'development' into development-restricted

Browse Source
This commit is contained in:
Jaeden Amero 2018-01-30 16:56:13 +00:00
commit 9564e97460
17 changed files with 2464 additions and 1866 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doxygen/mbedtls.doxyfile
View File

@ -165,7 +165,7 @@ SHORT_NAMES = NO
# comments will behave just like regular Qt-style comments # comments will behave just like regular Qt-style comments
# (thus requiring an explicit @brief command for a brief description.) # (thus requiring an explicit @brief command for a brief description.)
JAVADOC_AUTOBRIEF = YES JAVADOC_AUTOBRIEF = NO
# If the QT_AUTOBRIEF tag is set to YES then Doxygen will # If the QT_AUTOBRIEF tag is set to YES then Doxygen will
# interpret the first line (until the first dot) of a Qt-style # interpret the first line (until the first dot) of a Qt-style

328
include/mbedtls/aes.h
View File

@ -1,10 +1,18 @@
/** /**
* \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
* 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.
* Copyright (C) 2006-2015, ARM Limited, 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 +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
@ -34,15 +43,15 @@
#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 */ /* 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 */ /* Error codes in range 0x0023-0x0025 */
#define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE -0x0023 /**< Feature not available, e.g. unsupported AES key size. */ #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. */ #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) ) && \
@ -59,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.
* *
* \param ctx AES context to be initialized * It must be the first API called before using
* the context.
*
* \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 * It performs the operation defined in the \p mode parameter
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT * (encrypt or decrypt), on the input data buffer defined in
* \param input 16-byte input block * the \p input parameter.
* \param output 16-byte output block
* *
* \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,
@ -129,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)
* *
* \note Upon exit, the content of the IV is updated so that you can * It performs the operation defined in the \p mode
* call the function same function again on the following * parameter (encrypt/decrypt), on the input data buffer defined in
* block(s) of data and get the same result as if it was * the \p input parameter.
* encrypted in one call. This allows a "streaming" usage.
* If on the other hand you need to retain the contents of the
* IV, you should either save it manually or use the cipher
* module instead.
* *
* \param ctx AES context * It can be called as many times as needed, until all the input
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT * data is processed. mbedtls_aes_init(), and either
* \param length length of the input data * mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called
* \param iv initialization vector (updated after use) * before the first call to this API with the same context.
* \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 * \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
* call the same function again on the next
* block(s) of data and get the same result as if it was
* encrypted in one call. This allows a "streaming" usage.
* If you need to retain the contents of the IV, you should
* either save it manually or use the cipher module instead.
*
*
* \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,
@ -160,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.
* *
* Note: Due to the nature of CFB you should use the same key schedule for * It performs the operation defined in the \p mode
* both encryption and decryption. So a context initialized with * parameter (encrypt or decrypt), on the input data buffer
* mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. * defined in the \p input parameter.
* *
* \note Upon exit, the content of the IV is updated so that you can * For CFB, you must set up the context with mbedtls_aes_setkey_enc(),
* call the function same function again on the following * regardless of whether you are performing an encryption or decryption
* block(s) of data and get the same result as if it was * operation, that is, regardless of the \p mode parameter. This is
* encrypted in one call. This allows a "streaming" usage. * because CFB mode uses the same key schedule for encryption and
* If on the other hand you need to retain the contents of the * decryption.
* IV, you should either save it manually or use the cipher
* module instead.
* *
* \param ctx AES context * \note Upon exit, the content of the IV is updated so that you can
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT * call the same function again on the next
* \param length length of the input data * block(s) of data and get the same result as if it was
* \param iv_off offset in IV (updated after use) * encrypted in one call. This allows a "streaming" usage.
* \param iv initialization vector (updated after use) * If you need to retain the contents of the
* \param input buffer holding the input data * IV, you must either save it manually or use the cipher
* \param output buffer holding the output data * module instead.
* *
* \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,
@ -193,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.
* *
* Note: Due to the nature of CFB you should use the same key schedule for * It performs the operation defined in the \p mode
* both encryption and decryption. So a context initialized with * parameter (encrypt/decrypt), on the input data buffer defined
* mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. * in the \p input parameter.
* *
* \note Upon exit, the content of the IV is updated so that you can * Due to the nature of CFB, you must use the same key schedule for
* call the function same function again on the following * both encryption and decryption operations. Therefore, you must
* block(s) of data and get the same result as if it was * use the context initialized with mbedtls_aes_setkey_enc() for
* encrypted in one call. This allows a "streaming" usage. * both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
* If on the other hand you need to retain the contents of the
* IV, you should either save it manually or use the cipher
* module instead.
* *
* \param ctx AES context * \note Upon exit, the content of the IV is updated so that you can
* \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT * call the same function again on the next
* \param length length of the input data * block(s) of data and get the same result as if it was
* \param iv initialization vector (updated after use) * encrypted in one call. This allows a "streaming" usage.
* \param input buffer holding the input data * If you need to retain the contents of the
* \param output buffer holding the output data * IV, you should either save it manually or use the cipher
* module instead.
* *
* \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,
@ -226,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.
* *
* Warning: You have to keep the maximum use of your counter in mind! * This function 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 CTR you should use the same key schedule for * Due to the nature of CTR, you must use the same key schedule
* both encryption and decryption. So a context initialized with * for both encryption and decryption operations. Therefore, you
* mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. * must use the context initialized with mbedtls_aes_setkey_enc()
* for both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
* *
* \param ctx AES context * \warning You must keep the maximum use of your counter in mind.
* \param length The length of the data
* \param nc_off The offset in the current stream_block (for resuming
* within current cipher stream). The offset pointer to
* should be 0 at the start of a stream.
* \param nonce_counter The 128-bit nonce and counter.
* \param stream_block The saved stream-block for resuming. Is overwritten
* by the function.
* \param input The input data stream
* \param output The output data stream
* *
* \return 0 if successful * \param ctx The AES context to use for encryption or decryption.
* \param length The length of the input data.
* \param nc_off The offset in the current \p stream_block, for
* resuming within the current cipher stream. The
* offset pointer should be 0 at the start of a stream.
* \param nonce_counter The 128-bit nonce and counter.
* \param stream_block The saved stream block for resuming. This is
* overwritten by the function.
* \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_ctr( mbedtls_aes_context *ctx, int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx,
size_t length, size_t length,
@ -257,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],
@ -296,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],
@ -310,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],
@ -336,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 );

128
include/mbedtls/ccm.h
View File

@ -1,10 +1,19 @@
/** /**
* \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.
*
* 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-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
@ -19,16 +28,17 @@
* 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. */ #define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */
#if !defined(MBEDTLS_CCM_ALT) #if !defined(MBEDTLS_CCM_ALT)
// Regular implementation // Regular implementation
@ -39,31 +49,33 @@ 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,
@ -71,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 get the tag * \note The tag is written to a separate buffer. To concatenate
* concatenated with the output as in the CCM spec, use * the \p tag with the \p output, as done in <em>RFC-3610:
* tag = output + length and make sure the output buffer is * Counter with CBC-MAC (CCM)</em>, use
* at least length + tag_len wide. * \p tag = \p output + \p length, and make sure that the
* 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,
@ -109,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 ctx The CCM context to use for decryption.
* \param length length of the input data * \param length The length of the input data in Bytes.
* \param iv initialization vector * \param iv Initialization vector.
* \param iv_len length of IV * \param iv_len The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
* \param add additional data * \param add The additional data field.
* \param add_len length of additional data * \param add_len The length of additional data in Bytes.
* \param input buffer holding the input data * \param input The buffer holding the input data.
* \param output buffer for holding the output data * \param output The buffer holding the output data.
* \param tag buffer holding the tag * \param tag The buffer holding the tag.
* \param tag_len length of the tag * \param tag_len The length of the tag in Bytes.
* *
* \return 0 if successful and authenticated, * \return 0 if successful and authenticated, or
* MBEDTLS_ERR_CCM_AUTH_FAILED if tag does not match * #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,
@ -135,9 +149,9 @@ int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
} }
#endif #endif
#else /* !MBEDTLS_CCM_ALT */ #else /* MBEDTLS_CCM_ALT */
#include "ccm_alt.h" #include "ccm_alt.h"
#endif /* !MBEDTLS_CCM_ALT */ #endif /* MBEDTLS_CCM_ALT */
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
@ -145,9 +159,9 @@ extern "C" {
#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 */

527
include/mbedtls/cipher.h
View File

@ -1,12 +1,12 @@
/** /**
* \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
@ -21,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,22 +52,23 @@
#define inline __inline #define inline __inline
#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_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
/** Supported cipher IDs. */
typedef enum { typedef enum {
MBEDTLS_CIPHER_ID_NONE = 0, MBEDTLS_CIPHER_ID_NONE = 0,
MBEDTLS_CIPHER_ID_NULL, MBEDTLS_CIPHER_ID_NULL,
@ -79,6 +80,7 @@ typedef enum {
MBEDTLS_CIPHER_ID_ARC4, MBEDTLS_CIPHER_ID_ARC4,
} mbedtls_cipher_id_t; } mbedtls_cipher_id_t;
/** Supported cipher types. */
typedef enum { typedef enum {
MBEDTLS_CIPHER_NONE = 0, MBEDTLS_CIPHER_NONE = 0,
MBEDTLS_CIPHER_NULL, MBEDTLS_CIPHER_NULL,
@ -131,6 +133,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,
@ -143,14 +146,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,
@ -158,19 +163,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
/** /**
@ -184,33 +189,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;
@ -219,125 +231,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 * \param ctx The context to initialize. May not be NULL.
* will be required to call mbedtls_cipher_init() on the structure * \param cipher_info The cipher to use.
* first.
* *
* \param ctx context to initialise. May not be NULL. * \return \c 0 on success,
* \param cipher_info cipher to use. * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
* * #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
* \return 0 on success,
* MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
* 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 )
{ {
@ -348,13 +368,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 )
{ {
@ -365,13 +385,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 )
{ {
@ -385,12 +406,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 )
{ {
@ -401,11 +422,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 )
{ {
@ -416,13 +439,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 )
{ {
@ -433,13 +456,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 )
{ {
@ -450,18 +473,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,
@ -469,170 +492,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.
* *
* \param ctx generic cipher context * The default passing mode is PKCS7 padding.
* \param mode padding mode
* *
* \returns 0 on success, MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE * \param ctx The generic cipher context.
* if selected padding mode is not supported, or * \param mode The padding mode.
* MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode *
* \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
* if the selected padding mode is not supported, or
* #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
* 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 * \note Some ciphers do not use IVs nor nonce. For these
* ciphers, use iv = NULL and iv_len = 0. * ciphers, use \p iv = NULL and \p iv_len = 0.
* *
* \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_FULL_BLOCK_EXPECTED if decryption * #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
* expected a full block but was not provided one, or * expected a full block but was not provided one, 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,
@ -641,26 +670,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,
@ -670,31 +699,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,

153
include/mbedtls/cmac.h
View File

@ -1,11 +1,11 @@
/** /**
* \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
@ -20,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
@ -31,110 +32,125 @@
extern "C" { extern "C" {
#endif #endif
#define MBEDTLS_ERR_CMAC_HW_ACCEL_FAILED -0x007A /**< CMAC hardware accelerator failed. */ #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) #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().
* May be called repeatedly.
* *
* \param ctx CMAC context * It is called between mbedtls_cipher_cmac_starts() or
* \param input buffer holding the data * mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish().
* \param ilen length of the input data * Can be called repeatedly.
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The cipher context used for the CMAC operation.
* verification fails. * \param input The buffer holding the input data.
* \param ilen The length of the input data.
*
* \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().
* *
* \param ctx CMAC context * It is called after mbedtls_cipher_cmac_update().
* \param output Generic CMAC checksum result * It can be followed by mbedtls_cipher_cmac_reset() and
* mbedtls_cipher_cmac_update(), or mbedtls_cipher_free().
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The cipher context used for the CMAC operation.
* verification fails. * \param output The output buffer for the CMAC checksum result.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
* 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.
* *
* \param cipher_info message digest info * The function allocates the context, performs the
* \param key CMAC key * calculation, and frees the context.
* \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 * The CMAC result is calculated as
* verification fails. * output = generic CMAC(cmac key, input buffer).
*
*
* \param cipher_info The cipher information.
* \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,
@ -143,16 +159,21 @@ 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
* Message Authentication Code-Pseudo-Random Function-128
* (AES-CMAC-PRF-128) Algorithm for the Internet Key
* Exchange Protocol (IKE).</em>
* *
* \param key PRF key * \param key The key to use.
* \param key_len PRF key length in bytes * \param key_len The key length in Bytes.
* \param input buffer holding the input data * \param input The buffer holding the input data.
* \param in_len length of the input data in bytes * \param in_len The length of the input data in Bytes.
* \param output buffer holding the generated pseudorandom output (16 bytes) * \param output The buffer holding the generated 16 Bytes of
* pseudorandom output.
* *
* \return 0 if successful * \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,
@ -173,9 +194,9 @@ extern "C" {
#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 ) */

249
include/mbedtls/ctr_drbg.h
View File

@ -1,10 +1,13 @@
/** /**
* \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
@ -19,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
@ -31,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. */
int reseed_interval; /*!< The reseed interval. */
mbedtls_aes_context aes_ctx; /*!< AES context */ 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;
@ -111,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),
@ -144,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 );

242
include/mbedtls/dhm.h
View File

@ -1,7 +1,15 @@
/** /**
* \file dhm.h * \file dhm.h
* *
* \brief Diffie-Hellman-Merkle key exchange * \brief Diffie-Hellman-Merkle key exchange.
*
* <em>RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for
* Internet Key Exchange (IKE)</em> defines a number of standardized
* Diffie-Hellman groups for IKE.
*
* <em>RFC-5114: Additional Diffie-Hellman Groups for Use with IETF
* Standards</em> defines a number of standardized Diffie-Hellman
* groups that can be used.
* *
* \warning The security of the DHM key exchange relies on the proper choice * \warning The security of the DHM key exchange relies on the proper choice
* of prime modulus - optimally, it should be a safe prime. The usage * of prime modulus - optimally, it should be a safe prime. The usage
@ -30,7 +38,7 @@
* *
*/ */
/* /*
* 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
@ -45,9 +53,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_DHM_H #ifndef MBEDTLS_DHM_H
#define MBEDTLS_DHM_H #define MBEDTLS_DHM_H
@ -62,7 +70,7 @@
/* /*
* DHM Error codes * DHM Error codes
*/ */
#define MBEDTLS_ERR_DHM_BAD_INPUT_DATA -0x3080 /**< Bad input parameters to function. */ #define MBEDTLS_ERR_DHM_BAD_INPUT_DATA -0x3080 /**< Bad input parameters. */
#define MBEDTLS_ERR_DHM_READ_PARAMS_FAILED -0x3100 /**< Reading of the DHM parameters failed. */ #define MBEDTLS_ERR_DHM_READ_PARAMS_FAILED -0x3100 /**< Reading of the DHM parameters failed. */
#define MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED -0x3180 /**< Making of the DHM parameters failed. */ #define MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED -0x3180 /**< Making of the DHM parameters failed. */
#define MBEDTLS_ERR_DHM_READ_PUBLIC_FAILED -0x3200 /**< Reading of the public values failed. */ #define MBEDTLS_ERR_DHM_READ_PUBLIC_FAILED -0x3200 /**< Reading of the public values failed. */
@ -70,7 +78,7 @@
#define MBEDTLS_ERR_DHM_CALC_SECRET_FAILED -0x3300 /**< Calculation of the DHM secret failed. */ #define MBEDTLS_ERR_DHM_CALC_SECRET_FAILED -0x3300 /**< Calculation of the DHM secret failed. */
#define MBEDTLS_ERR_DHM_INVALID_FORMAT -0x3380 /**< The ASN.1 data is not formatted correctly. */ #define MBEDTLS_ERR_DHM_INVALID_FORMAT -0x3380 /**< The ASN.1 data is not formatted correctly. */
#define MBEDTLS_ERR_DHM_ALLOC_FAILED -0x3400 /**< Allocation of memory failed. */ #define MBEDTLS_ERR_DHM_ALLOC_FAILED -0x3400 /**< Allocation of memory failed. */
#define MBEDTLS_ERR_DHM_FILE_IO_ERROR -0x3480 /**< Read/write of file failed. */ #define MBEDTLS_ERR_DHM_FILE_IO_ERROR -0x3480 /**< Read or write of file failed. */
#define MBEDTLS_ERR_DHM_HW_ACCEL_FAILED -0x3500 /**< DHM hardware accelerator failed. */ #define MBEDTLS_ERR_DHM_HW_ACCEL_FAILED -0x3500 /**< DHM hardware accelerator failed. */
#define MBEDTLS_ERR_DHM_SET_GROUP_FAILED -0x3580 /**< Setting the modulus and generator failed. */ #define MBEDTLS_ERR_DHM_SET_GROUP_FAILED -0x3580 /**< Setting the modulus and generator failed. */
@ -79,35 +87,35 @@ extern "C" {
#endif #endif
/** /**
* \brief DHM context structure * \brief The DHM context structure.
*/ */
typedef struct typedef struct
{ {
size_t len; /*!< size(P) in chars */ size_t len; /*!< The size of \p P in Bytes. */
mbedtls_mpi P; /*!< prime modulus */ mbedtls_mpi P; /*!< The prime modulus. */
mbedtls_mpi G; /*!< generator */ mbedtls_mpi G; /*!< The generator. */
mbedtls_mpi X; /*!< secret value */ mbedtls_mpi X; /*!< Our secret value. */
mbedtls_mpi GX; /*!< self = G^X mod P */ mbedtls_mpi GX; /*!< Our public key = \c G^X mod \c P. */
mbedtls_mpi GY; /*!< peer = G^Y mod P */ mbedtls_mpi GY; /*!< The public key of the peer = \c G^Y mod \c P. */
mbedtls_mpi K; /*!< key = GY^X mod P */ mbedtls_mpi K; /*!< The shared secret = \c G^(XY) mod \c P. */
mbedtls_mpi RP; /*!< cached R^2 mod P */ mbedtls_mpi RP; /*!< The cached value = \c R^2 mod \c P. */
mbedtls_mpi Vi; /*!< blinding value */ mbedtls_mpi Vi; /*!< The blinding value. */
mbedtls_mpi Vf; /*!< un-blinding value */ mbedtls_mpi Vf; /*!< The unblinding value. */
mbedtls_mpi pX; /*!< previous X */ mbedtls_mpi pX; /*!< The previous \c X. */
} }
mbedtls_dhm_context; mbedtls_dhm_context;
/** /**
* \brief Initialize DHM context * \brief This function initializes the DHM context.
* *
* \param ctx DHM context to be initialized * \param ctx The DHM context to initialize.
*/ */
void mbedtls_dhm_init( mbedtls_dhm_context *ctx ); void mbedtls_dhm_init( mbedtls_dhm_context *ctx );
/** /**
* \brief Parse the ServerKeyExchange parameters * \brief This function parses the ServerKeyExchange parameters.
* *
* \param ctx DHM context * \param ctx The DHM context.
* \param p On input, *p must be the start of the input buffer. * \param p On input, *p must be the start of the input buffer.
* On output, *p is updated to point to the end of the data * On output, *p is updated to point to the end of the data
* that has been read. On success, this is the first byte * that has been read. On success, this is the first byte
@ -115,23 +123,25 @@ void mbedtls_dhm_init( mbedtls_dhm_context *ctx );
* On error, this is the point at which an error has been * On error, this is the point at which an error has been
* detected, which is usually not useful except to debug * detected, which is usually not useful except to debug
* failures. * failures.
* \param end end of buffer * \param end The end of the input buffer.
* *
* \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
* on failure.
*/ */
int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx, int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx,
unsigned char **p, unsigned char **p,
const unsigned char *end ); const unsigned char *end );
/** /**
* \brief Setup and write the ServerKeyExchange parameters * \brief This function sets up and writes the ServerKeyExchange
* parameters.
* *
* \param ctx DHM context * \param ctx The DHM context.
* \param x_size private value size in bytes * \param x_size The private value size in Bytes.
* \param output destination buffer * \param olen The number of characters written.
* \param olen number of chars written * \param output The destination buffer.
* \param f_rng RNG function * \param f_rng The RNG function.
* \param p_rng RNG parameter * \param p_rng The RNG parameter.
* *
* \note The destination buffer must be large enough to hold * \note The destination buffer must be large enough to hold
* the reduced binary presentation of the modulus, the generator * the reduced binary presentation of the modulus, the generator
@ -140,12 +150,13 @@ int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx,
* space is available. Refer to \c mbedtls_mpi_size to computing * space is available. Refer to \c mbedtls_mpi_size to computing
* the byte-size of an MPI. * the byte-size of an MPI.
* *
* \note This function assumes that ctx->P and ctx->G * \note This function assumes that \c ctx->P and \c ctx->G
* have already been properly set. For that, use * have already been properly set. For that, use
* \c mbedtls_dhm_set_group below in conjunction with * mbedtls_dhm_set_group() below in conjunction with
* \c mbedtls_mpi_read_binary and \c mbedtls_mpi_read_string. * mbedtls_mpi_read_binary() and mbedtls_mpi_read_string().
* *
* \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
* on failure.
*/ */
int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size, int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size,
unsigned char *output, size_t *olen, unsigned char *output, size_t *olen,
@ -155,48 +166,52 @@ int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size,
/** /**
* \brief Set prime modulus and generator * \brief Set prime modulus and generator
* *
* \param ctx DHM context * \param ctx The DHM context.
* \param P MPI holding DHM prime modulus * \param P The MPI holding DHM prime modulus.
* \param G MPI holding DHM generator * \param G The MPI holding DHM generator.
* *
* \note This function can be used to set P, G * \note This function can be used to set P, G
* in preparation for \c mbedtls_dhm_make_params. * in preparation for \c mbedtls_dhm_make_params.
* *
* \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code * \return \c 0 if successful, or an \c MBEDTLS_ERR_DHM_XXX error code
* on failure.
*/ */
int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx, int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx,
const mbedtls_mpi *P, const mbedtls_mpi *P,
const mbedtls_mpi *G ); const mbedtls_mpi *G );
/** /**
* \brief Import the peer's public value G^Y * \brief This function imports the public value G^Y of the peer.
* *
* \param ctx DHM context * \param ctx The DHM context.
* \param input input buffer * \param input The input buffer.
* \param ilen size of buffer * \param ilen The size of the input buffer.
* *
* \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
* on failure.
*/ */
int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx, int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx,
const unsigned char *input, size_t ilen ); const unsigned char *input, size_t ilen );
/** /**
* \brief Create own private value X and export G^X * \brief This function creates its own private value \c X and
* exports \c G^X.
* *
* \param ctx DHM context * \param ctx The DHM context.
* \param x_size private value size in bytes * \param x_size The private value size in Bytes.
* \param output destination buffer * \param output The destination buffer.
* \param olen size of the destination buffer; * \param olen The length of the destination buffer. Must be at least
* must be at least equal to the size of P, ctx->len equal to ctx->len (the size of \c P).
* \param f_rng RNG function * \param f_rng The RNG function.
* \param p_rng RNG parameter * \param p_rng The RNG parameter.
* *
* \note The destination buffer will always be fully written * \note The destination buffer will always be fully written
* so as to contain a big-endian presentation of G^X mod P. * so as to contain a big-endian presentation of G^X mod P.
* If it is larger than ctx->len, it will accordingly be * If it is larger than ctx->len, it will accordingly be
* padded with zero-bytes in the beginning. * padded with zero-bytes in the beginning.
* *
* \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
* on failure.
*/ */
int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size, int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size,
unsigned char *output, size_t olen, unsigned char *output, size_t olen,
@ -204,23 +219,25 @@ int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size,
void *p_rng ); void *p_rng );
/** /**
* \brief Derive and export the shared secret (G^Y)^X mod P * \brief This function derives and exports the shared secret
* \c (G^Y)^X mod \c P.
* *
* \param ctx DHM context * \param ctx The DHM context.
* \param output destination buffer * \param output The destination buffer.
* \param output_size size of the destination buffer, must be at * \param output_size The size of the destination buffer. Must be at least
* at least the size of ctx->len * the size of ctx->len.
* \param olen on exit, holds the actual number of bytes written * \param olen On exit, holds the actual number of Bytes written.
* \param f_rng RNG function, for blinding purposes * \param f_rng The RNG function, for blinding purposes.
* \param p_rng RNG parameter * \param p_rng The RNG parameter.
* *
* \return 0 if successful, or an MBEDTLS_ERR_DHM_XXX error code * \return \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
* on failure.
* *
* \note If non-NULL, f_rng is used to blind the input as * \note If non-NULL, \p f_rng is used to blind the input as
* countermeasure against timing attacks. Blinding is * a countermeasure against timing attacks. Blinding is used
* automatically used if and only if our secret value X is * only if our secret value \p X is re-used and omitted
* re-used and costs nothing otherwise, so it is recommended * otherwise. Therefore, we recommend always passing a
* to always pass a non-NULL f_rng argument. * non-NULL \p f_rng argument.
*/ */
int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx, int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx,
unsigned char *output, size_t output_size, size_t *olen, unsigned char *output, size_t output_size, size_t *olen,
@ -228,23 +245,24 @@ int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx,
void *p_rng ); void *p_rng );
/** /**
* \brief Free and clear the components of a DHM key * \brief This function frees and clears the components of a DHM key.
* *
* \param ctx DHM context to free and clear * \param ctx The DHM context to free and clear.
*/ */
void mbedtls_dhm_free( mbedtls_dhm_context *ctx ); void mbedtls_dhm_free( mbedtls_dhm_context *ctx );
#if defined(MBEDTLS_ASN1_PARSE_C) #if defined(MBEDTLS_ASN1_PARSE_C)
/** \ingroup x509_module */ /** \ingroup x509_module */
/** /**
* \brief Parse DHM parameters in PEM or DER format * \brief This function parses DHM parameters in PEM or DER format.
* *
* \param dhm DHM context to be initialized * \param dhm The DHM context to initialize.
* \param dhmin input buffer * \param dhmin The input buffer.
* \param dhminlen size of the buffer * \param dhminlen The size of the buffer, including the terminating null
* (including the terminating null byte for PEM data) * Byte for PEM data.
* *
* \return 0 if successful, or a specific DHM or PEM error code * \return \c 0 on success, or a specific DHM or PEM error code
* on failure.
*/ */
int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin, int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
size_t dhminlen ); size_t dhminlen );
@ -252,12 +270,13 @@ int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
#if defined(MBEDTLS_FS_IO) #if defined(MBEDTLS_FS_IO)
/** \ingroup x509_module */ /** \ingroup x509_module */
/** /**
* \brief Load and parse DHM parameters * \brief This function loads and parses DHM parameters from a file.
* *
* \param dhm DHM context to be initialized * \param dhm The DHM context to load the parameters to.
* \param path filename to read the DHM Parameters from * \param path The filename to read the DHM parameters from.
* *
* \return 0 if successful, or a specific DHM or PEM error code * \return \c 0 on success, or a specific DHM or PEM error code
* on failure.
*/ */
int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path ); int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path );
#endif /* MBEDTLS_FS_IO */ #endif /* MBEDTLS_FS_IO */
@ -276,9 +295,9 @@ extern "C" {
#endif #endif
/** /**
* \brief Checkup routine * \brief The DMH checkup routine.
* *
* \return 0 if successful, or 1 if the test failed * \return \c 0 on success, or \c 1 on failure.
*/ */
int mbedtls_dhm_self_test( int verbose ); int mbedtls_dhm_self_test( int verbose );
@ -293,16 +312,16 @@ int mbedtls_dhm_self_test( int verbose );
* when configuring the Diffie-Hellman parameters by hand * when configuring the Diffie-Hellman parameters by hand
* through \c mbedtls_ssl_conf_dh_param. * through \c mbedtls_ssl_conf_dh_param.
* *
* Included are: * The following lists the source of the above groups in the standards:
* RFC 5114 2.2. 2048-bit MODP Group with 224-bit Prime Order Subgroup * - RFC 5114 section 2.2: 2048-bit MODP Group with 224-bit Prime Order Subgroup
* RFC 3526 3. 2048-bit MODP Group * - RFC 3526 section 3: 2048-bit MODP Group
* RFC 3526 4. 3072-bit MODP Group * - RFC 3526 section 4: 3072-bit MODP Group
* RFC 3526 5. 4096-bit MODP Group * - RFC 3526 section 5: 4096-bit MODP Group
* RFC 7919 A.1 ffdhe2048 * - RFC 7919 section A.1: ffdhe2048
* RFC 7919 A.2 ffdhe3072 * - RFC 7919 section A.2: ffdhe3072
* RFC 7919 A.3 ffdhe4096 * - RFC 7919 section A.3: ffdhe4096
* RFC 7919 A.4 ffdhe6144 * - RFC 7919 section A.4: ffdhe6144
* RFC 7919 A.5 ffdhe8192 * - RFC 7919 section A.5: ffdhe8192
* *
* The constants with suffix "_p" denote the chosen prime moduli, while * The constants with suffix "_p" denote the chosen prime moduli, while
* the constants with suffix "_g" denote the chosen generator * the constants with suffix "_g" denote the chosen generator
@ -347,6 +366,12 @@ MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t;
* replacement. * replacement.
*/ */
/**
* The hexadecimal presentation of the prime underlying the
* 2048-bit MODP Group with 224-bit Prime Order Subgroup, as defined
* in <em>RFC-5114: Additional Diffie-Hellman Groups for Use with
* IETF Standards</em>.
*/
#define MBEDTLS_DHM_RFC5114_MODP_P \ #define MBEDTLS_DHM_RFC5114_MODP_P \
MBEDTLS_DEPRECATED_STRING_CONSTANT( \ MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"AD107E1E9123A9D0D660FAA79559C51FA20D64E5683B9FD1" \ "AD107E1E9123A9D0D660FAA79559C51FA20D64E5683B9FD1" \
@ -361,6 +386,11 @@ MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t;
"C9B53DCF4BA80A29E3FB73C16B8E75B97EF363E2FFA31F71" \ "C9B53DCF4BA80A29E3FB73C16B8E75B97EF363E2FFA31F71" \
"CF9DE5384E71B81C0AC4DFFE0C10E64F" ) "CF9DE5384E71B81C0AC4DFFE0C10E64F" )
/**
* The hexadecimal presentation of the chosen generator of the 2048-bit MODP
* Group with 224-bit Prime Order Subgroup, as defined in <em>RFC-5114:
* Additional Diffie-Hellman Groups for Use with IETF Standards</em>.
*/
#define MBEDTLS_DHM_RFC5114_MODP_2048_G \ #define MBEDTLS_DHM_RFC5114_MODP_2048_G \
MBEDTLS_DEPRECATED_STRING_CONSTANT( \ MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"AC4032EF4F2D9AE39DF30B5C8FFDAC506CDEBE7B89998CAF" \ "AC4032EF4F2D9AE39DF30B5C8FFDAC506CDEBE7B89998CAF" \
@ -376,13 +406,16 @@ MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t;
"81BC087F2A7065B384B890D3191F2BFA" ) "81BC087F2A7065B384B890D3191F2BFA" )
/** /**
* The hexadecimal presentation of the prime underlying the 2048-bit MODP
* Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
* Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
*
* \deprecated The hex-encoded primes from RFC 3625 are deprecated and * \deprecated The hex-encoded primes from RFC 3625 are deprecated and
* superseded by the corresponding macros providing them as * superseded by the corresponding macros providing them as
* binary constants. Their hex-encoded constants are likely * binary constants. Their hex-encoded constants are likely
* to be removed in a future version of the library. * to be removed in a future version of the library.
* *
*/ */
#define MBEDTLS_DHM_RFC3526_MODP_2048_P \ #define MBEDTLS_DHM_RFC3526_MODP_2048_P \
MBEDTLS_DEPRECATED_STRING_CONSTANT( \ MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \ "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
@ -397,9 +430,19 @@ MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t;
"DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \ "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \
"15728E5A8AACAA68FFFFFFFFFFFFFFFF" ) "15728E5A8AACAA68FFFFFFFFFFFFFFFF" )
/**
* The hexadecimal presentation of the chosen generator of the 2048-bit MODP
* Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
* Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
*/
#define MBEDTLS_DHM_RFC3526_MODP_2048_G \ #define MBEDTLS_DHM_RFC3526_MODP_2048_G \
MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" ) MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )
/**
* The hexadecimal presentation of the prime underlying the 3072-bit MODP
* Group, as defined in <em>RFC-3072: More Modular Exponential (MODP)
* Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
*/
#define MBEDTLS_DHM_RFC3526_MODP_3072_P \ #define MBEDTLS_DHM_RFC3526_MODP_3072_P \
MBEDTLS_DEPRECATED_STRING_CONSTANT( \ MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \ "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
@ -419,9 +462,19 @@ MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t;
"BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \ "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \
"43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF" ) "43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF" )
/**
* The hexadecimal presentation of the chosen generator of the 3072-bit MODP
* Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
* Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
*/
#define MBEDTLS_DHM_RFC3526_MODP_3072_G \ #define MBEDTLS_DHM_RFC3526_MODP_3072_G \
MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" ) MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )
/**
* The hexadecimal presentation of the prime underlying the 4096-bit MODP
* Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
* Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
*/
#define MBEDTLS_DHM_RFC3526_MODP_4096_P \ #define MBEDTLS_DHM_RFC3526_MODP_4096_P \
MBEDTLS_DEPRECATED_STRING_CONSTANT( \ MBEDTLS_DEPRECATED_STRING_CONSTANT( \
"FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \ "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \
@ -447,6 +500,11 @@ MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t;
"93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934063199" \ "93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934063199" \
"FFFFFFFFFFFFFFFF" ) "FFFFFFFFFFFFFFFF" )
/**
* The hexadecimal presentation of the chosen generator of the 4096-bit MODP
* Group, as defined in <em>RFC-3526: More Modular Exponential (MODP)
* Diffie-Hellman groups for Internet Key Exchange (IKE)</em>.
*/
#define MBEDTLS_DHM_RFC3526_MODP_4096_G \ #define MBEDTLS_DHM_RFC3526_MODP_4096_G \
MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" ) MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" )

238
include/mbedtls/ecdh.h
View File

@ -1,10 +1,18 @@
/** /**
* \file ecdh.h * \file ecdh.h
* *
* \brief Elliptic curve Diffie-Hellman * \brief The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs.
*
* ECDH is an anonymous key agreement protocol allowing two parties to
* establish a shared secret over an insecure channel. Each party must have an
* elliptic-curve public–private key pair.
*
* For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for
* Pair-Wise Key Establishment Schemes Using Discrete Logarithm
* Cryptography</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
@ -19,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_ECDH_H #ifndef MBEDTLS_ECDH_H
#define MBEDTLS_ECDH_H #define MBEDTLS_ECDH_H
@ -31,7 +40,9 @@ extern "C" {
#endif #endif
/** /**
* When importing from an EC key, select if it is our key or the peer's key * Defines the source of the imported EC key:
* <ul><li>Our key.</li>
* <li>The key of the peer.</li></ul>
*/ */
typedef enum typedef enum
{ {
@ -40,56 +51,67 @@ typedef enum
} mbedtls_ecdh_side; } mbedtls_ecdh_side;
/** /**
* \brief ECDH context structure * \brief The ECDH context structure.
*/ */
typedef struct typedef struct
{ {
mbedtls_ecp_group grp; /*!< elliptic curve used */ mbedtls_ecp_group grp; /*!< The elliptic curve used. */
mbedtls_mpi d; /*!< our secret value (private key) */ mbedtls_mpi d; /*!< The private key. */
mbedtls_ecp_point Q; /*!< our public value (public key) */ mbedtls_ecp_point Q; /*!< The public key. */
mbedtls_ecp_point Qp; /*!< peer's public value (public key) */ mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */
mbedtls_mpi z; /*!< shared secret */ mbedtls_mpi z; /*!< The shared secret. */
int point_format; /*!< format for point export in TLS messages */ int point_format; /*!< The format of point export in TLS messages. */
mbedtls_ecp_point Vi; /*!< blinding value (for later) */ mbedtls_ecp_point Vi; /*!< The blinding value. */
mbedtls_ecp_point Vf; /*!< un-blinding value (for later) */ mbedtls_ecp_point Vf; /*!< The unblinding value. */
mbedtls_mpi _d; /*!< previous d (for later) */ mbedtls_mpi _d; /*!< The previous \p d. */
} }
mbedtls_ecdh_context; mbedtls_ecdh_context;
/** /**
* \brief Generate a public key. * \brief This function generates an ECDH keypair on an elliptic
* Raw function that only does the core computation. * curve.
* *
* \param grp ECP group * This function performs the first of two core computations
* \param d Destination MPI (secret exponent, aka private key) * implemented during the ECDH key exchange. The second core
* \param Q Destination point (public key) * computation is performed by mbedtls_ecdh_compute_shared().
* \param f_rng RNG function
* \param p_rng RNG parameter
* *
* \return 0 if successful, * \param grp The ECP group.
* or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code * \param d The destination MPI (private key).
* \param Q The destination point (public key).
* \param f_rng The RNG function.
* \param p_rng The RNG parameter.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
* \c MBEDTLS_MPI_XXX error code on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q, int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
int (*f_rng)(void *, unsigned char *, size_t), int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng ); void *p_rng );
/** /**
* \brief Compute shared secret * \brief This function computes the shared secret.
* Raw function that only does the core computation.
* *
* \param grp ECP group * This function performs the second of two core computations
* \param z Destination MPI (shared secret) * implemented during the ECDH key exchange. The first core
* \param Q Public key from other party * computation is performed by mbedtls_ecdh_gen_public().
* \param d Our secret exponent (private key)
* \param f_rng RNG function (see notes)
* \param p_rng RNG parameter
* *
* \return 0 if successful, * \param grp The ECP group.
* or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code * \param z The destination MPI (shared secret).
* \param Q The public key from another party.
* \param d Our secret exponent (private key).
* \param f_rng The RNG function.
* \param p_rng The RNG parameter.
* *
* \note If f_rng is not NULL, it is used to implement * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
* \c MBEDTLS_MPI_XXX error code on failure.
*
* \see ecp.h
*
* \note If \p f_rng is not NULL, it is used to implement
* countermeasures against potential elaborate timing * countermeasures against potential elaborate timing
* attacks, see \c mbedtls_ecp_mul() for details. * attacks. For more information, see mbedtls_ecp_mul().
*/ */
int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z, int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
const mbedtls_ecp_point *Q, const mbedtls_mpi *d, const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
@ -97,34 +119,41 @@ int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
void *p_rng ); void *p_rng );
/** /**
* \brief Initialize context * \brief This function initializes an ECDH context.
* *
* \param ctx Context to initialize * \param ctx The ECDH context to initialize.
*/ */
void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx ); void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
/** /**
* \brief Free context * \brief This function frees a context.
* *
* \param ctx Context to free * \param ctx The context to free.
*/ */
void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx ); void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
/** /**
* \brief Generate a public key and a TLS ServerKeyExchange payload. * \brief This function generates a public key and a TLS
* (First function used by a TLS server for ECDHE.) * ServerKeyExchange payload.
* *
* \param ctx ECDH context * This is the first function used by a TLS server for ECDHE
* \param olen number of chars written * ciphersuites.
* \param buf destination buffer
* \param blen length of buffer
* \param f_rng RNG function
* \param p_rng RNG parameter
* *
* \note This function assumes that ctx->grp has already been * \param ctx The ECDH context.
* properly set (for example using mbedtls_ecp_group_load). * \param olen The number of characters written.
* \param buf The destination buffer.
* \param blen The length of the destination buffer.
* \param f_rng The RNG function.
* \param p_rng The RNG parameter.
* *
* \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code * \note This function assumes that the ECP group (grp) of the
* \p ctx context has already been properly set,
* for example, using mbedtls_ecp_group_load().
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
* on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen, int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
unsigned char *buf, size_t blen, unsigned char *buf, size_t blen,
@ -132,45 +161,63 @@ int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
void *p_rng ); void *p_rng );
/** /**
* \brief Parse and procress a TLS ServerKeyExhange payload. * \brief This function parses and processes a TLS ServerKeyExhange
* (First function used by a TLS client for ECDHE.) * payload.
* *
* \param ctx ECDH context * This is the first function used by a TLS client for ECDHE
* \param buf pointer to start of input buffer * ciphersuites.
* \param end one past end of buffer
* *
* \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code * \param ctx The ECDH context.
* \param buf The pointer to the start of the input buffer.
* \param end The address for one Byte past the end of the buffer.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
* on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx, int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
const unsigned char **buf, const unsigned char *end ); const unsigned char **buf, const unsigned char *end );
/** /**
* \brief Setup an ECDH context from an EC key. * \brief This function sets up an ECDH context from an EC key.
* (Used by clients and servers in place of the
* ServerKeyEchange for static ECDH: import ECDH parameters
* from a certificate's EC key information.)
* *
* \param ctx ECDH constext to set * It is used by clients and servers in place of the
* \param key EC key to use * ServerKeyEchange for static ECDH, and imports ECDH
* \param side Is it our key (1) or the peer's key (0) ? * parameters from the EC key information of a certificate.
* *
* \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code * \param ctx The ECDH context to set up.
* \param key The EC key to use.
* \param side Defines the source of the key:
* <ul><li>1: Our key.</li>
<li>0: The key of the peer.</li></ul>
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
* on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key, int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
mbedtls_ecdh_side side ); mbedtls_ecdh_side side );
/** /**
* \brief Generate a public key and a TLS ClientKeyExchange payload. * \brief This function generates a public key and a TLS
* (Second function used by a TLS client for ECDH(E).) * ClientKeyExchange payload.
* *
* \param ctx ECDH context * This is the second function used by a TLS client for ECDH(E)
* \param olen number of bytes actually written * ciphersuites.
* \param buf destination buffer
* \param blen size of destination buffer
* \param f_rng RNG function
* \param p_rng RNG parameter
* *
* \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code * \param ctx The ECDH context.
* \param olen The number of Bytes written.
* \param buf The destination buffer.
* \param blen The size of the destination buffer.
* \param f_rng The RNG function.
* \param p_rng The RNG parameter.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
* on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen, int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
unsigned char *buf, size_t blen, unsigned char *buf, size_t blen,
@ -178,30 +225,45 @@ int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
void *p_rng ); void *p_rng );
/** /**
* \brief Parse and process a TLS ClientKeyExchange payload. * \brief This function parses and processes a TLS ClientKeyExchange
* (Second function used by a TLS server for ECDH(E).) * payload.
* *
* \param ctx ECDH context * This is the second function used by a TLS server for ECDH(E)
* \param buf start of input buffer * ciphersuites.
* \param blen length of input buffer
* *
* \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code * \param ctx The ECDH context.
* \param buf The start of the input buffer.
* \param blen The length of the input buffer.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
* on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx, int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
const unsigned char *buf, size_t blen ); const unsigned char *buf, size_t blen );
/** /**
* \brief Derive and export the shared secret. * \brief This function derives and exports the shared secret.
* (Last function used by both TLS client en servers.)
* *
* \param ctx ECDH context * This is the last function used by both TLS client
* \param olen number of bytes written * and servers.
* \param buf destination buffer
* \param blen buffer length
* \param f_rng RNG function, see notes for \c mbedtls_ecdh_compute_shared()
* \param p_rng RNG parameter
* *
* \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code * \param ctx The ECDH context.
* \param olen The number of Bytes written.
* \param buf The destination buffer.
* \param blen The length of the destination buffer.
* \param f_rng The RNG function.
* \param p_rng The RNG parameter.
*
* \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
* on failure.
*
* \see ecp.h
*
* \note If \p f_rng is not NULL, it is used to implement
* countermeasures against potential elaborate timing
* attacks. For more information, see mbedtls_ecp_mul().
*/ */
int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen, int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
unsigned char *buf, size_t blen, unsigned char *buf, size_t blen,

275
include/mbedtls/ecdsa.h
View File

@ -1,10 +1,16 @@
/** /**
* \file ecdsa.h * \file ecdsa.h
* *
* \brief Elliptic curve DSA * \brief The Elliptic Curve Digital Signature Algorithm (ECDSA).
*
* ECDSA is defined in <em>Standards for Efficient Cryptography Group (SECG):
* SEC1 Elliptic Curve Cryptography</em>.
* The use of ECDSA for TLS is defined in <em>RFC-4492: Elliptic Curve
* Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</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
@ -19,8 +25,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_ECDSA_H #ifndef MBEDTLS_ECDSA_H
#define MBEDTLS_ECDSA_H #define MBEDTLS_ECDSA_H
@ -28,7 +35,7 @@
#include "md.h" #include "md.h"
/* /*
* RFC 4492 page 20: * RFC-4492 page 20:
* *
* Ecdsa-Sig-Value ::= SEQUENCE { * Ecdsa-Sig-Value ::= SEQUENCE {
* r INTEGER, * r INTEGER,
@ -44,11 +51,11 @@
#if MBEDTLS_ECP_MAX_BYTES > 124 #if MBEDTLS_ECP_MAX_BYTES > 124
#error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN" #error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN"
#endif #endif
/** Maximum size of an ECDSA signature in bytes */ /** The maximal size of an ECDSA signature in Bytes. */
#define MBEDTLS_ECDSA_MAX_LEN ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) ) #define MBEDTLS_ECDSA_MAX_LEN ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
/** /**
* \brief ECDSA context structure * \brief The ECDSA context structure.
*/ */
typedef mbedtls_ecp_keypair mbedtls_ecdsa_context; typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
@ -57,25 +64,30 @@ extern "C" {
#endif #endif
/** /**
* \brief Compute ECDSA signature of a previously hashed message * \brief This function computes the ECDSA signature of a
* previously-hashed message.
* *
* \note The deterministic version is usually prefered. * \note The deterministic version is usually preferred.
* *
* \param grp ECP group * \param grp The ECP group.
* \param r First output integer * \param r The first output integer.
* \param s Second output integer * \param s The second output integer.
* \param d Private signing key * \param d The private signing key.
* \param buf Message hash * \param buf The message hash.
* \param blen Length of buf * \param blen The length of \p buf.
* \param f_rng RNG function * \param f_rng The RNG function.
* \param p_rng RNG parameter * \param p_rng The RNG parameter.
* *
* \note If the bitlength of the message hash is larger than the * \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as * bitlength of the group order, then the hash is truncated
* prescribed by SEC1 4.1.3 step 5. * as defined in <em>Standards for Efficient Cryptography Group
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5.
* *
* \return 0 if successful, * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX
* or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code * or \c MBEDTLS_MPI_XXX error code on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
const mbedtls_mpi *d, const unsigned char *buf, size_t blen, const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
@ -83,23 +95,31 @@ int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
#if defined(MBEDTLS_ECDSA_DETERMINISTIC) #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
/** /**
* \brief Compute ECDSA signature of a previously hashed message, * \brief This function computes the ECDSA signature of a
* deterministic version (RFC 6979). * previously-hashed message, deterministic version.
* For more information, see <em>RFC-6979: Deterministic
* Usage of the Digital Signature Algorithm (DSA) and Elliptic
* Curve Digital Signature Algorithm (ECDSA)</em>.
* *
* \param grp ECP group * \param grp The ECP group.
* \param r First output integer * \param r The first output integer.
* \param s Second output integer * \param s The second output integer.
* \param d Private signing key * \param d The private signing key.
* \param buf Message hash * \param buf The message hash.
* \param blen Length of buf * \param blen The length of \p buf.
* \param md_alg MD algorithm used to hash the message * \param md_alg The MD algorithm used to hash the message.
* *
* \note If the bitlength of the message hash is larger than the * \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as * bitlength of the group order, then the hash is truncated as
* prescribed by SEC1 4.1.3 step 5. * defined in <em>Standards for Efficient Cryptography Group
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5.
* *
* \return 0 if successful, * \return \c 0 on success,
* or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* error code on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
const mbedtls_mpi *d, const unsigned char *buf, size_t blen, const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
@ -107,55 +127,73 @@ int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi
#endif /* MBEDTLS_ECDSA_DETERMINISTIC */ #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
/** /**
* \brief Verify ECDSA signature of a previously hashed message * \brief This function verifies the ECDSA signature of a
* previously-hashed message.
* *
* \param grp ECP group * \param grp The ECP group.
* \param buf Message hash * \param buf The message hash.
* \param blen Length of buf * \param blen The length of \p buf.
* \param Q Public key to use for verification * \param Q The public key to use for verification.
* \param r First integer of the signature * \param r The first integer of the signature.
* \param s Second integer of the signature * \param s The second integer of the signature.
* *
* \note If the bitlength of the message hash is larger than the * \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as * bitlength of the group order, then the hash is truncated as
* prescribed by SEC1 4.1.4 step 3. * defined in <em>Standards for Efficient Cryptography Group
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.4, step 3.
* *
* \return 0 if successful, * \return \c 0 on success,
* MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid * #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
* or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
* error code on failure for any other reason.
*
* \see ecp.h
*/ */
int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp, int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
const unsigned char *buf, size_t blen, const unsigned char *buf, size_t blen,
const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s); const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s);
/** /**
* \brief Compute ECDSA signature and write it to buffer, * \brief This function computes the ECDSA signature and writes it
* serialized as defined in RFC 4492 page 20. * to a buffer, serialized as defined in <em>RFC-4492:
* (Not thread-safe to use same context in multiple threads) * Elliptic Curve Cryptography (ECC) Cipher Suites for
* Transport Layer Security (TLS)</em>.
* *
* \note The deterministic version (RFC 6979) is used if * \warning It is not thread-safe to use the same context in
* MBEDTLS_ECDSA_DETERMINISTIC is defined. * multiple threads.
* *
* \param ctx ECDSA context * \note The deterministic version is used if
* \param md_alg Algorithm that was used to hash the message * #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more
* \param hash Message hash * information, see <em>RFC-6979: Deterministic Usage
* \param hlen Length of hash * of the Digital Signature Algorithm (DSA) and Elliptic
* \param sig Buffer that will hold the signature * Curve Digital Signature Algorithm (ECDSA)</em>.
* \param slen Length of the signature written
* \param f_rng RNG function
* \param p_rng RNG parameter
* *
* \note The "sig" buffer must be at least as large as twice the * \param ctx The ECDSA context.
* size of the curve used, plus 9 (eg. 73 bytes if a 256-bit * \param md_alg The message digest that was used to hash the message.
* curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe. * \param hash The message hash.
* \param hlen The length of the hash.
* \param sig The buffer that holds the signature.
* \param slen The length of the signature written.
* \param f_rng The RNG function.
* \param p_rng The RNG parameter.
*
* \note The \p sig buffer must be at least twice as large as the
* size of the curve used, plus 9. For example, 73 Bytes if
* a 256-bit curve is used. A buffer length of
* #MBEDTLS_ECDSA_MAX_LEN is always safe.
* *
* \note If the bitlength of the message hash is larger than the * \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as * bitlength of the group order, then the hash is truncated as
* prescribed by SEC1 4.1.3 step 5. * defined in <em>Standards for Efficient Cryptography Group
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5.
* *
* \return 0 if successful, * \return \c 0 on success,
* or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or * or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
* MBEDTLS_ERR_ASN1_XXX error code * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg, int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg,
const unsigned char *hash, size_t hlen, const unsigned char *hash, size_t hlen,
@ -171,31 +209,43 @@ int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, mbedtls_md_type_t
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief Compute ECDSA signature and write it to buffer, * \brief This function computes an ECDSA signature and writes it to a buffer,
* serialized as defined in RFC 4492 page 20. * serialized as defined in <em>RFC-4492: Elliptic Curve Cryptography
* Deterministic version, RFC 6979. * (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
* (Not thread-safe to use same context in multiple threads) *
* The deterministic version is defined in <em>RFC-6979:
* Deterministic Usage of the Digital Signature Algorithm (DSA) and
* Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
*
* \warning It is not thread-safe to use the same context in
* multiple threads.
* *
* \deprecated Superseded by mbedtls_ecdsa_write_signature() in 2.0.0 * \deprecated Superseded by mbedtls_ecdsa_write_signature() in 2.0.0
* *
* \param ctx ECDSA context * \param ctx The ECDSA context.
* \param hash Message hash * \param hash The Message hash.
* \param hlen Length of hash * \param hlen The length of the hash.
* \param sig Buffer that will hold the signature * \param sig The buffer that holds the signature.
* \param slen Length of the signature written * \param slen The length of the signature written.
* \param md_alg MD algorithm used to hash the message * \param md_alg The MD algorithm used to hash the message.
* *
* \note The "sig" buffer must be at least as large as twice the * \note The \p sig buffer must be at least twice as large as the
* size of the curve used, plus 9 (eg. 73 bytes if a 256-bit * size of the curve used, plus 9. For example, 73 Bytes if a
* curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe. * 256-bit curve is used. A buffer length of
* #MBEDTLS_ECDSA_MAX_LEN is always safe.
* *
* \note If the bitlength of the message hash is larger than the * \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as * bitlength of the group order, then the hash is truncated as
* prescribed by SEC1 4.1.3 step 5. * defined in <em>Standards for Efficient Cryptography Group
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.3, step 5.
* *
* \return 0 if successful, * \return \c 0 on success,
* or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or * or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
* MBEDTLS_ERR_ASN1_XXX error code * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx, int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
const unsigned char *hash, size_t hlen, const unsigned char *hash, size_t hlen,
@ -206,63 +256,74 @@ int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
#endif /* MBEDTLS_ECDSA_DETERMINISTIC */ #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
/** /**
* \brief Read and verify an ECDSA signature * \brief This function reads and verifies an ECDSA signature.
* *
* \param ctx ECDSA context * \param ctx The ECDSA context.
* \param hash Message hash * \param hash The message hash.
* \param hlen Size of hash * \param hlen The size of the hash.
* \param sig Signature to read and verify * \param sig The signature to read and verify.
* \param slen Size of sig * \param slen The size of \p sig.
* *
* \note If the bitlength of the message hash is larger than the * \note If the bitlength of the message hash is larger than the
* bitlength of the group order, then the hash is truncated as * bitlength of the group order, then the hash is truncated as
* prescribed by SEC1 4.1.4 step 3. * defined in <em>Standards for Efficient Cryptography Group
* (SECG): SEC1 Elliptic Curve Cryptography</em>, section
* 4.1.4, step 3.
* *
* \return 0 if successful, * \return \c 0 on success,
* MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid, * #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid,
* MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is * #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is
* valid but its actual length is less than siglen, * valid but its actual length is less than \p siglen,
* or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX error code * or an \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
* error code on failure for any other reason.
*
* \see ecp.h
*/ */
int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx, int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
const unsigned char *hash, size_t hlen, const unsigned char *hash, size_t hlen,
const unsigned char *sig, size_t slen ); const unsigned char *sig, size_t slen );
/** /**
* \brief Generate an ECDSA keypair on the given curve * \brief This function generates an ECDSA keypair on the given curve.
* *
* \param ctx ECDSA context in which the keypair should be stored * \param ctx The ECDSA context to store the keypair in.
* \param gid Group (elliptic curve) to use. One of the various * \param gid The elliptic curve to use. One of the various
* MBEDTLS_ECP_DP_XXX macros depending on configuration. * \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
* \param f_rng RNG function * \param f_rng The RNG function.
* \param p_rng RNG parameter * \param p_rng The RNG parameter.
* *
* \return 0 on success, or a MBEDTLS_ERR_ECP_XXX code. * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
* failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid, int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
/** /**
* \brief Set an ECDSA context from an EC key pair * \brief This function sets an ECDSA context from an EC key pair.
* *
* \param ctx ECDSA context to set * \param ctx The ECDSA context to set.
* \param key EC key to use * \param key The EC key to use.
* *
* \return 0 on success, or a MBEDTLS_ERR_ECP_XXX code. * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX code on
* failure.
*
* \see ecp.h
*/ */
int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key ); int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key );
/** /**
* \brief Initialize context * \brief This function initializes an ECDSA context.
* *
* \param ctx Context to initialize * \param ctx The ECDSA context to initialize.
*/ */
void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx ); void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
/** /**
* \brief Free context * \brief This function frees an ECDSA context.
* *
* \param ctx Context to free * \param ctx The ECDSA context to free.
*/ */
void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx ); void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );

194
include/mbedtls/gcm.h
View File

@ -1,10 +1,16 @@
/** /**
* \file gcm.h * \file gcm.h
* *
* \brief Galois/Counter mode for 128-bit block ciphers * \brief Galois/Counter Mode (GCM) for 128-bit block ciphers, as defined
* in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
* (GCM), Natl. Inst. Stand. Technol.</em>
*
* For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
* Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</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
@ -19,8 +25,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_GCM_H #ifndef MBEDTLS_GCM_H
#define MBEDTLS_GCM_H #define MBEDTLS_GCM_H
@ -42,39 +49,49 @@ extern "C" {
#endif #endif
/** /**
* \brief GCM context structure * \brief The GCM context structure.
*/ */
typedef struct { typedef struct {
mbedtls_cipher_context_t cipher_ctx;/*!< cipher context used */ mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */
uint64_t HL[16]; /*!< Precalculated HTable */ uint64_t HL[16]; /*!< Precalculated HTable low. */
uint64_t HH[16]; /*!< Precalculated HTable */ uint64_t HH[16]; /*!< Precalculated HTable high. */
uint64_t len; /*!< Total data length */ uint64_t len; /*!< The total length of the encrypted data. */
uint64_t add_len; /*!< Total add length */ uint64_t add_len; /*!< The total length of the additional data. */
unsigned char base_ectr[16];/*!< First ECTR for tag */ unsigned char base_ectr[16]; /*!< The first ECTR for tag. */
unsigned char y[16]; /*!< Y working value */ unsigned char y[16]; /*!< The Y working value. */
unsigned char buf[16]; /*!< buf working value */ unsigned char buf[16]; /*!< The buf working value. */
int mode; /*!< Encrypt or Decrypt */ int mode; /*!< The operation to perform:
#MBEDTLS_GCM_ENCRYPT or
#MBEDTLS_GCM_DECRYPT. */
} }
mbedtls_gcm_context; mbedtls_gcm_context;
/** /**
* \brief Initialize GCM context (just makes references valid) * \brief This function initializes the specified GCM context,
* Makes the context ready for mbedtls_gcm_setkey() or * to make references valid, and prepares the context
* mbedtls_gcm_free(). * for mbedtls_gcm_setkey() or mbedtls_gcm_free().
* *
* \param ctx GCM context to initialize * The function does not bind the GCM context to a particular
* cipher, nor set the key. For this purpose, use
* mbedtls_gcm_setkey().
*
* \param ctx The GCM context to initialize.
*/ */
void mbedtls_gcm_init( mbedtls_gcm_context *ctx ); void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
/** /**
* \brief GCM initialization (encryption) * \brief This function associates a GCM context with a
* cipher algorithm and a key.
* *
* \param ctx GCM context to be initialized * \param ctx The GCM 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 must be 128, 192 or 256 * \param keybits The key size in bits. Valid options are:
* <ul><li>128 bits</li>
* <li>192 bits</li>
* <li>256 bits</li></ul>
* *
* \return 0 if successful, or a cipher specific error code * \return \c 0 on success, or a cipher specific error code.
*/ */
int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx, int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
mbedtls_cipher_id_t cipher, mbedtls_cipher_id_t cipher,
@ -82,26 +99,27 @@ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
unsigned int keybits ); unsigned int keybits );
/** /**
* \brief GCM buffer encryption/decryption using a block cipher * \brief This function performs GCM encryption or decryption of a buffer.
* *
* \note On encryption, the output buffer can be the same as the input buffer. * \note For encryption, the output buffer can be the same as the input buffer.
* On decryption, the output buffer cannot be the same as input buffer. * For decryption, the output buffer cannot be the same as input buffer.
* If buffers overlap, the output buffer must trail at least 8 bytes * If the buffers overlap, the output buffer must trail at least 8 Bytes
* behind the input buffer. * behind the input buffer.
* *
* \param ctx GCM context * \param ctx The GCM context to use for encryption or decryption.
* \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or
* \param length length of the input data * #MBEDTLS_GCM_DECRYPT.
* \param iv initialization vector * \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
* \param iv_len length of IV * \param iv The initialization vector.
* \param add additional data * \param iv_len The length of the IV.
* \param add_len length of additional data * \param add The buffer holding the additional data.
* \param input buffer holding the input data * \param add_len The length of the additional data.
* \param output buffer for holding the output data * \param input The buffer holding the input data.
* \param tag_len length of the tag to generate * \param output The buffer for holding the output data.
* \param tag buffer for holding the tag * \param tag_len The length of the tag to generate.
* \param tag The buffer for holding the tag.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx, int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
int mode, int mode,
@ -116,25 +134,26 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
unsigned char *tag ); unsigned char *tag );
/** /**
* \brief GCM buffer authenticated decryption using a block cipher * \brief This function performs a GCM authenticated decryption of a
* buffer.
* *
* \note On decryption, the output buffer cannot be the same as input buffer. * \note For decryption, the output buffer cannot be the same as input buffer.
* If buffers overlap, the output buffer must trail at least 8 bytes * If the buffers overlap, the output buffer must trail at least 8 Bytes
* behind the input buffer. * behind the input buffer.
* *
* \param ctx GCM context * \param ctx The GCM context.
* \param length length of the input data * \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
* \param iv initialization vector * \param iv The initialization vector.
* \param iv_len length of IV * \param iv_len The length of the IV.
* \param add additional data * \param add The buffer holding the additional data.
* \param add_len length of additional data * \param add_len The length of the additional data.
* \param tag buffer holding the tag * \param tag The buffer holding the tag.
* \param tag_len length of the tag * \param tag_len The length of the tag.
* \param input buffer holding the input data * \param input The buffer holding the input data.
* \param output buffer for holding the output data * \param output The buffer for holding the output data.
* *
* \return 0 if successful and authenticated, * \return 0 if successful and authenticated, or
* MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match * #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match.
*/ */
int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx, int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
size_t length, size_t length,
@ -148,16 +167,18 @@ int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
unsigned char *output ); unsigned char *output );
/** /**
* \brief Generic GCM stream start function * \brief This function starts a GCM encryption or decryption
* operation.
* *
* \param ctx GCM context * \param ctx The GCM context.
* \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or
* \param iv initialization vector * #MBEDTLS_GCM_DECRYPT.
* \param iv_len length of IV * \param iv The initialization vector.
* \param add additional data (or NULL if length is 0) * \param iv_len The length of the IV.
* \param add_len length of additional data * \param add The buffer holding the additional data, or NULL if \p add_len is 0.
* \param add_len The length of the additional data. If 0, \p add is NULL.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_gcm_starts( mbedtls_gcm_context *ctx, int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
int mode, int mode,
@ -167,21 +188,23 @@ int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
size_t add_len ); size_t add_len );
/** /**
* \brief Generic GCM update function. Encrypts/decrypts using the * \brief This function feeds an input buffer into an ongoing GCM
* given GCM context. Expects input to be a multiple of 16 * encryption or decryption operation.
* bytes! Only the last call before mbedtls_gcm_finish() can be less
* than 16 bytes!
* *
* \note On decryption, the output buffer cannot be the same as input buffer. * ` The function expects input to be a multiple of 16
* If buffers overlap, the output buffer must trail at least 8 bytes * Bytes. Only the last call before calling
* mbedtls_gcm_finish() can be less than 16 Bytes.
*
* \note For decryption, the output buffer cannot be the same as input buffer.
* If the buffers overlap, the output buffer must trail at least 8 Bytes
* behind the input buffer. * behind the input buffer.
* *
* \param ctx GCM context * \param ctx The GCM context.
* \param length length of the input data * \param length The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
* \param input buffer holding the input data * \param input The buffer holding the input data.
* \param output buffer for holding the output data * \param output The buffer for holding the output data.
* *
* \return 0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT * \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
*/ */
int mbedtls_gcm_update( mbedtls_gcm_context *ctx, int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
size_t length, size_t length,
@ -189,24 +212,27 @@ int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
unsigned char *output ); unsigned char *output );
/** /**
* \brief Generic GCM finalisation function. Wraps up the GCM stream * \brief This function finishes the GCM operation and generates
* and generates the tag. The tag can have a maximum length of * the authentication tag.
* 16 bytes.
* *
* \param ctx GCM context * It wraps up the GCM stream, and generates the
* \param tag buffer for holding the tag * tag. The tag can have a maximum length of 16 Bytes.
* \param tag_len length of the tag to generate (must be at least 4)
* *
* \return 0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT * \param ctx The GCM context.
* \param tag The buffer for holding the tag.
* \param tag_len The length of the tag to generate. Must be at least four.
*
* \return \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
*/ */
int mbedtls_gcm_finish( mbedtls_gcm_context *ctx, int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
unsigned char *tag, unsigned char *tag,
size_t tag_len ); size_t tag_len );
/** /**
* \brief Free a GCM context and underlying cipher sub-context * \brief This function clears a GCM context and the underlying
* cipher sub-context.
* *
* \param ctx GCM context to free * \param ctx The GCM context to clear.
*/ */
void mbedtls_gcm_free( mbedtls_gcm_context *ctx ); void mbedtls_gcm_free( mbedtls_gcm_context *ctx );
@ -223,9 +249,9 @@ extern "C" {
#endif #endif
/** /**
* \brief Checkup routine * \brief The GCM checkup routine.
* *
* \return 0 if successful, or 1 if the test failed * \return \c 0 on success, or \c 1 on failure.
*/ */
int mbedtls_gcm_self_test( int verbose ); int mbedtls_gcm_self_test( int verbose );

349
include/mbedtls/md.h
View File

@ -1,12 +1,12 @@
/** /**
* \file md.h * \file md.h
* *
* \brief Generic message digest wrapper * \brief The generic message-digest 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
@ -21,8 +21,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_MD_H #ifndef MBEDTLS_MD_H
#define MBEDTLS_MD_H #define MBEDTLS_MD_H
@ -64,65 +65,79 @@ typedef enum {
#endif #endif
/** /**
* Opaque struct defined in md_internal.h * Opaque struct defined in md_internal.h.
*/ */
typedef struct mbedtls_md_info_t mbedtls_md_info_t; typedef struct mbedtls_md_info_t mbedtls_md_info_t;
/** /**
* Generic message digest context. * The generic message-digest context.
*/ */
typedef struct { typedef struct {
/** Information about the associated message digest */ /** Information about the associated message digest. */
const mbedtls_md_info_t *md_info; const mbedtls_md_info_t *md_info;
/** Digest-specific context */ /** The digest-specific context. */
void *md_ctx; void *md_ctx;
/** HMAC part of the context */ /** The HMAC part of the context. */
void *hmac_ctx; void *hmac_ctx;
} mbedtls_md_context_t; } mbedtls_md_context_t;
/** /**
* \brief Returns the list of digests supported by the generic digest module. * \brief This function returns the list of digests supported by the
* generic digest module.
* *
* \return a statically allocated array of digests, the last entry * \return A statically allocated array of digests. Each element
* is 0. * in the returned list is an integer belonging to the
* message-digest enumeration #mbedtls_md_type_t.
* The last entry is 0.
*/ */
const int *mbedtls_md_list( void ); const int *mbedtls_md_list( void );
/** /**
* \brief Returns the message digest information associated with the * \brief This function returns the message-digest information
* given digest name. * associated with the given digest name.
* *
* \param md_name Name of the digest to search for. * \param md_name The name of the digest to search for.
* *
* \return The message digest information associated with md_name or * \return The message-digest information associated with \p md_name,
* NULL if not found. * or NULL if not found.
*/ */
const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name ); const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name );
/** /**
* \brief Returns the message digest information associated with the * \brief This function returns the message-digest information
* given digest type. * associated with the given digest type.
* *
* \param md_type type of digest to search for. * \param md_type The type of digest to search for.
* *
* \return The message digest information associated with md_type or * \return The message-digest information associated with \p md_type,
* NULL if not found. * or NULL if not found.
*/ */
const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type ); const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type );
/** /**
* \brief Initialize a md_context (as NONE) * \brief This function initializes a message-digest context without
* This should always be called first. * binding it to a particular message-digest algorithm.
* Prepares the context for mbedtls_md_setup() or mbedtls_md_free(). *
* This function should always be called first. It prepares the
* context for mbedtls_md_setup() for binding it to a
* message-digest algorithm.
*/ */
void mbedtls_md_init( mbedtls_md_context_t *ctx ); void mbedtls_md_init( mbedtls_md_context_t *ctx );
/** /**
* \brief Free and clear the internal structures of ctx. * \brief This function clears the internal structure of \p ctx and
* Can be called at any time after mbedtls_md_init(). * frees any embedded internal structure, but does not free
* Mandatory once mbedtls_md_setup() has been called. * \p ctx itself.
*
* If you have called mbedtls_md_setup() on \p ctx, you must
* call mbedtls_md_free() when you are no longer using the
* context.
* Calling this function if you have previously
* called mbedtls_md_init() and nothing else is optional.
* You must not call this function if you have not called
* mbedtls_md_init().
*/ */
void mbedtls_md_free( mbedtls_md_context_t *ctx ); void mbedtls_md_free( mbedtls_md_context_t *ctx );
@ -133,220 +148,288 @@ void mbedtls_md_free( mbedtls_md_context_t *ctx );
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief Select MD to use and allocate internal structures. * \brief This function selects the message digest algorithm to use,
* Should be called after mbedtls_md_init() or mbedtls_md_free(). * and allocates internal structures.
*
* It should be called after mbedtls_md_init() or mbedtls_md_free().
* Makes it necessary to call mbedtls_md_free() later. * Makes it necessary to call mbedtls_md_free() later.
* *
* \deprecated Superseded by mbedtls_md_setup() in 2.0.0 * \deprecated Superseded by mbedtls_md_setup() in 2.0.0
* *
* \param ctx Context to set up. * \param ctx The context to set up.
* \param md_info Message digest to use. * \param md_info The information structure of the message-digest algorithm
* to use.
* *
* \returns \c 0 on success, * \returns \c 0 on success,
* \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure,
* \c MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure. * #MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.
*/ */
int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED; int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED;
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* MBEDTLS_DEPRECATED_REMOVED */ #endif /* MBEDTLS_DEPRECATED_REMOVED */
/** /**
* \brief Select MD to use and allocate internal structures. * \brief This function selects the message digest algorithm to use,
* Should be called after mbedtls_md_init() or mbedtls_md_free(). * and allocates internal structures.
* Makes it necessary to call mbedtls_md_free() later.
* *
* \param ctx Context to set up. * It should be called after mbedtls_md_init() or
* \param md_info Message digest to use. * mbedtls_md_free(). Makes it necessary to call
* \param hmac 0 to save some memory if HMAC will not be used, * mbedtls_md_free() later.
* non-zero is HMAC is going to be used with this context. *
* \param ctx The context to set up.
* \param md_info The information structure of the message-digest algorithm
* to use.
* \param hmac <ul><li>0: HMAC is not used. Saves some memory.</li>
* <li>non-zero: HMAC is used with this context.</li></ul>
* *
* \returns \c 0 on success, * \returns \c 0 on success,
* \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, or
* \c MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure. * #MBEDTLS_ERR_MD_ALLOC_FAILED on memory allocation failure.
*/ */
int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac ); int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac );
/** /**
* \brief Clone the state of an MD context * \brief This function clones the state of an message-digest
* context.
* *
* \note The two contexts must have been setup to the same type * \note You must call mbedtls_md_setup() on \c dst before calling
* (cloning from SHA-256 to SHA-512 make no sense). * this function.
* *
* \warning Only clones the MD state, not the HMAC state! (for now) * \note The two contexts must have the same type,
* for example, both are SHA-256.
* *
* \param dst The destination context * \warning This function clones the message-digest state, not the
* \param src The context to be cloned * HMAC state.
*
* \param dst The destination context.
* \param src The context to be cloned.
* *
* \return \c 0 on success, * \return \c 0 on success,
* \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure. * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.
*/ */
int mbedtls_md_clone( mbedtls_md_context_t *dst, int mbedtls_md_clone( mbedtls_md_context_t *dst,
const mbedtls_md_context_t *src ); const mbedtls_md_context_t *src );
/** /**
* \brief Returns the size of the message digest output. * \brief This function extracts the message-digest size from the
* message-digest information structure.
* *
* \param md_info message digest info * \param md_info The information structure of the message-digest algorithm
* to use.
* *
* \return size of the message digest output in bytes. * \return The size of the message-digest output in Bytes.
*/ */
unsigned char mbedtls_md_get_size( const mbedtls_md_info_t *md_info ); unsigned char mbedtls_md_get_size( const mbedtls_md_info_t *md_info );
/** /**
* \brief Returns the type of the message digest output. * \brief This function extracts the message-digest type from the
* message-digest information structure.
* *
* \param md_info message digest info * \param md_info The information structure of the message-digest algorithm
* to use.
* *
* \return type of the message digest output. * \return The type of the message digest.
*/ */
mbedtls_md_type_t mbedtls_md_get_type( const mbedtls_md_info_t *md_info ); mbedtls_md_type_t mbedtls_md_get_type( const mbedtls_md_info_t *md_info );
/** /**
* \brief Returns the name of the message digest output. * \brief This function extracts the message-digest name from the
* message-digest information structure.
* *
* \param md_info message digest info * \param md_info The information structure of the message-digest algorithm
* to use.
* *
* \return name of the message digest output. * \return The name of the message digest.
*/ */
const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info ); const char *mbedtls_md_get_name( const mbedtls_md_info_t *md_info );
/** /**
* \brief Prepare the context to digest a new message. * \brief This function starts a message-digest computation.
* Generally called after mbedtls_md_setup() or mbedtls_md_finish().
* Followed by mbedtls_md_update().
* *
* \param ctx generic message digest context. * You must call this function after setting up the context
* with mbedtls_md_setup(), and before passing data with
* mbedtls_md_update().
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The generic message-digest context.
* verification fails. *
* \returns \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_starts( mbedtls_md_context_t *ctx ); int mbedtls_md_starts( mbedtls_md_context_t *ctx );
/** /**
* \brief Generic message digest process buffer * \brief This function feeds an input buffer into an ongoing
* Called between mbedtls_md_starts() and mbedtls_md_finish(). * message-digest computation.
* May be called repeatedly.
* *
* \param ctx Generic message digest context * You must call mbedtls_md_starts() before calling this
* \param input buffer holding the datal * function. You may call this function multiple times.
* \param ilen length of the input data * Afterwards, call mbedtls_md_finish().
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The generic message-digest context.
* verification fails. * \param input The buffer holding the input data.
* \param ilen The length of the input data.
*
* \returns \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen ); int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen );
/** /**
* \brief Generic message digest final digest * \brief This function finishes the digest operation,
* Called after mbedtls_md_update(). * and writes the result to the output buffer.
* Usually followed by mbedtls_md_free() or mbedtls_md_starts().
* *
* \param ctx Generic message digest context * Call this function after a call to mbedtls_md_starts(),
* \param output Generic message digest checksum result * followed by any number of calls to mbedtls_md_update().
* Afterwards, you may either clear the context with
* mbedtls_md_free(), or call mbedtls_md_starts() to reuse
* the context for another digest operation with the same
* algorithm.
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The generic message-digest context.
* verification fails. * \param output The buffer for the generic message-digest checksum result.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output ); int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output );
/** /**
* \brief Output = message_digest( input buffer ) * \brief This function calculates the message-digest of a buffer,
* with respect to a configurable message-digest algorithm
* in a single call.
* *
* \param md_info message digest info * The result is calculated as
* \param input buffer holding the data * Output = message_digest(input buffer).
* \param ilen length of the input data
* \param output Generic message digest checksum result
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param md_info The information structure of the message-digest algorithm
* verification fails. * to use.
* \param input The buffer holding the data.
* \param ilen The length of the input data.
* \param output The generic message-digest checksum result.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen, int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
unsigned char *output ); unsigned char *output );
#if defined(MBEDTLS_FS_IO) #if defined(MBEDTLS_FS_IO)
/** /**
* \brief Output = message_digest( file contents ) * \brief This function calculates the message-digest checksum
* result of the contents of the provided file.
* *
* \param md_info message digest info * The result is calculated as
* \param path input file name * Output = message_digest(file contents).
* \param output generic message digest checksum result
* *
* \return 0 if successful, * \param md_info The information structure of the message-digest algorithm
* MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed, * to use.
* MBEDTLS_ERR_MD_BAD_INPUT_DATA if md_info was NULL. * \param path The input file name.
* \param output The generic message-digest checksum result.
*
* \return \c 0 on success,
* #MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed, or
* #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
*/ */
int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path, int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path,
unsigned char *output ); unsigned char *output );
#endif /* MBEDTLS_FS_IO */ #endif /* MBEDTLS_FS_IO */
/** /**
* \brief Set HMAC key and prepare to authenticate a new message. * \brief This function sets the HMAC key and prepares to
* Usually called after mbedtls_md_setup() or mbedtls_md_hmac_finish(). * authenticate a new message.
* *
* \param ctx HMAC context * Call this function after mbedtls_md_setup(), to use
* \param key HMAC secret key * the MD context for an HMAC calculation, then call
* \param keylen length of the HMAC key in bytes * mbedtls_md_hmac_update() to provide the input data, and
* mbedtls_md_hmac_finish() to get the HMAC value.
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The message digest context containing an embedded HMAC
* verification fails. * context.
* \param key The HMAC secret key.
* \param keylen The length of the HMAC key in Bytes.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key, int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key,
size_t keylen ); size_t keylen );
/** /**
* \brief Generic HMAC process buffer. * \brief This function feeds an input buffer into an ongoing HMAC
* Called between mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset() * computation.
* and mbedtls_md_hmac_finish().
* May be called repeatedly.
* *
* \param ctx HMAC context * Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset()
* \param input buffer holding the data * before calling this function.
* \param ilen length of the input data * You may call this function multiple times to pass the
* input piecewise.
* Afterwards, call mbedtls_md_hmac_finish().
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The message digest context containing an embedded HMAC
* verification fails. * context.
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input, int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input,
size_t ilen ); size_t ilen );
/** /**
* \brief Output HMAC. * \brief This function finishes the HMAC operation, and writes
* Called after mbedtls_md_hmac_update(). * the result to the output buffer.
* Usually followed by mbedtls_md_hmac_reset(),
* mbedtls_md_hmac_starts(), or mbedtls_md_free().
* *
* \param ctx HMAC context * Call this function after mbedtls_md_hmac_starts() and
* \param output Generic HMAC checksum result * mbedtls_md_hmac_update() to get the HMAC value. Afterwards
* you may either call mbedtls_md_free() to clear the context,
* or call mbedtls_md_hmac_reset() to reuse the context with
* the same HMAC key.
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The message digest context containing an embedded HMAC
* verification fails. * context.
* \param output The generic HMAC checksum result.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output); int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output);
/** /**
* \brief Prepare to authenticate a new message with the same key. * \brief This function prepares to authenticate a new message with
* Called after mbedtls_md_hmac_finish() and before * the same key as the previous HMAC operation.
* mbedtls_md_hmac_update().
* *
* \param ctx HMAC context to be reset * You may call this function after mbedtls_md_hmac_finish().
* Afterwards call mbedtls_md_hmac_update() to pass the new
* input.
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * \param ctx The message digest context containing an embedded HMAC
* verification fails. * context.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx ); int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx );
/** /**
* \brief Output = Generic_HMAC( hmac key, input buffer ) * \brief This function calculates the full generic HMAC
* on the input buffer with the provided key.
* *
* \param md_info message digest info * The function allocates the context, performs the
* \param key HMAC secret key * calculation, and frees the context.
* \param keylen length of the HMAC key in bytes
* \param input buffer holding the data
* \param ilen length of the input data
* \param output Generic HMAC-result
* *
* \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter * The HMAC result is calculated as
* verification fails. * output = generic HMAC(hmac key, input buffer).
*
* \param md_info The information structure of the message-digest algorithm
* to use.
* \param key The HMAC secret key.
* \param keylen The length of the HMAC secret key in Bytes.
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
* \param output The generic HMAC result.
*
* \returns \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA if
* parameter verification fails.
*/ */
int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen, int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
const unsigned char *input, size_t ilen, const unsigned char *input, size_t ilen,

104
include/mbedtls/platform.h
View File

@ -1,10 +1,10 @@
/** /**
* \file platform.h * \file platform.h
* *
* \brief mbed TLS Platform abstraction layer * \brief The Mbed TLS platform abstraction layer.
*/ */
/* /*
* Copyright (C) 2006-2016, ARM Limited, All Rights Reserved * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * 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,7 +19,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_PLATFORM_H #ifndef MBEDTLS_PLATFORM_H
#define MBEDTLS_PLATFORM_H #define MBEDTLS_PLATFORM_H
@ -52,34 +52,34 @@ extern "C" {
#include <time.h> #include <time.h>
#if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF) #if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF)
#if defined(_WIN32) #if defined(_WIN32)
#define MBEDTLS_PLATFORM_STD_SNPRINTF mbedtls_platform_win32_snprintf /**< Default snprintf to use */ #define MBEDTLS_PLATFORM_STD_SNPRINTF mbedtls_platform_win32_snprintf /**< The default \c snprintf function to use. */
#else #else
#define MBEDTLS_PLATFORM_STD_SNPRINTF snprintf /**< Default snprintf to use */ #define MBEDTLS_PLATFORM_STD_SNPRINTF snprintf /**< The default \c snprintf function to use. */
#endif #endif
#endif #endif
#if !defined(MBEDTLS_PLATFORM_STD_PRINTF) #if !defined(MBEDTLS_PLATFORM_STD_PRINTF)
#define MBEDTLS_PLATFORM_STD_PRINTF printf /**< Default printf to use */ #define MBEDTLS_PLATFORM_STD_PRINTF printf /**< The default \c printf function to use. */
#endif #endif
#if !defined(MBEDTLS_PLATFORM_STD_FPRINTF) #if !defined(MBEDTLS_PLATFORM_STD_FPRINTF)
#define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< Default fprintf to use */ #define MBEDTLS_PLATFORM_STD_FPRINTF fprintf /**< The default \c fprintf function to use. */
#endif #endif
#if !defined(MBEDTLS_PLATFORM_STD_CALLOC) #if !defined(MBEDTLS_PLATFORM_STD_CALLOC)
#define MBEDTLS_PLATFORM_STD_CALLOC calloc /**< Default allocator to use */ #define MBEDTLS_PLATFORM_STD_CALLOC calloc /**< The default \c calloc function to use. */
#endif #endif
#if !defined(MBEDTLS_PLATFORM_STD_FREE) #if !defined(MBEDTLS_PLATFORM_STD_FREE)
#define MBEDTLS_PLATFORM_STD_FREE free /**< Default free to use */ #define MBEDTLS_PLATFORM_STD_FREE free /**< The default \c free function to use. */
#endif #endif
#if !defined(MBEDTLS_PLATFORM_STD_EXIT) #if !defined(MBEDTLS_PLATFORM_STD_EXIT)
#define MBEDTLS_PLATFORM_STD_EXIT exit /**< Default exit to use */ #define MBEDTLS_PLATFORM_STD_EXIT exit /**< The default \c exit function to use. */
#endif #endif
#if !defined(MBEDTLS_PLATFORM_STD_TIME) #if !defined(MBEDTLS_PLATFORM_STD_TIME)
#define MBEDTLS_PLATFORM_STD_TIME time /**< Default time to use */ #define MBEDTLS_PLATFORM_STD_TIME time /**< The default \c time function to use. */
#endif #endif
#if !defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS) #if !defined(MBEDTLS_PLATFORM_STD_EXIT_SUCCESS)
#define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS EXIT_SUCCESS /**< Default exit value to use */ #define MBEDTLS_PLATFORM_STD_EXIT_SUCCESS EXIT_SUCCESS /**< The default exit value to use. */
#endif #endif
#if !defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE) #if !defined(MBEDTLS_PLATFORM_STD_EXIT_FAILURE)
#define MBEDTLS_PLATFORM_STD_EXIT_FAILURE EXIT_FAILURE /**< Default exit value to use */ #define MBEDTLS_PLATFORM_STD_EXIT_FAILURE EXIT_FAILURE /**< The default exit value to use. */
#endif #endif
#if defined(MBEDTLS_FS_IO) #if defined(MBEDTLS_FS_IO)
#if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_READ) #if !defined(MBEDTLS_PLATFORM_STD_NV_SEED_READ)
@ -116,12 +116,12 @@ extern void * (*mbedtls_calloc)( size_t n, size_t size );
extern void (*mbedtls_free)( void *ptr ); extern void (*mbedtls_free)( void *ptr );
/** /**
* \brief Set your own memory implementation function pointers * \brief This function allows configuring custom memory-management functions.
* *
* \param calloc_func the calloc function implementation * \param calloc_func The \c calloc function implementation.
* \param free_func the free function implementation * \param free_func The \c free function implementation.
* *
* \return 0 if successful * \return \c 0.
*/ */
int mbedtls_platform_set_calloc_free( void * (*calloc_func)( size_t, size_t ), int mbedtls_platform_set_calloc_free( void * (*calloc_func)( size_t, size_t ),
void (*free_func)( void * ) ); void (*free_func)( void * ) );
@ -140,11 +140,11 @@ int mbedtls_platform_set_calloc_free( void * (*calloc_func)( size_t, size_t ),
extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... ); extern int (*mbedtls_fprintf)( FILE *stream, const char *format, ... );
/** /**
* \brief Set your own fprintf function pointer * \brief This function allows configuring a custom \p fprintf function pointer.
* *
* \param fprintf_func the fprintf function implementation * \param fprintf_func The \c fprintf function implementation.
* *
* \return 0 * \return \c 0.
*/ */
int mbedtls_platform_set_fprintf( int (*fprintf_func)( FILE *stream, const char *, int mbedtls_platform_set_fprintf( int (*fprintf_func)( FILE *stream, const char *,
... ) ); ... ) );
@ -163,11 +163,12 @@ int mbedtls_platform_set_fprintf( int (*fprintf_func)( FILE *stream, const char
extern int (*mbedtls_printf)( const char *format, ... ); extern int (*mbedtls_printf)( const char *format, ... );
/** /**
* \brief Set your own printf function pointer * \brief This function allows configuring a custom \c printf function
* pointer.
* *
* \param printf_func the printf function implementation * \param printf_func The \c printf function implementation.
* *
* \return 0 * \return \c 0 on success.
*/ */
int mbedtls_platform_set_printf( int (*printf_func)( const char *, ... ) ); int mbedtls_platform_set_printf( int (*printf_func)( const char *, ... ) );
#else /* !MBEDTLS_PLATFORM_PRINTF_ALT */ #else /* !MBEDTLS_PLATFORM_PRINTF_ALT */
@ -196,11 +197,12 @@ int mbedtls_platform_win32_snprintf( char *s, size_t n, const char *fmt, ... );
extern int (*mbedtls_snprintf)( char * s, size_t n, const char * format, ... ); extern int (*mbedtls_snprintf)( char * s, size_t n, const char * format, ... );
/** /**
* \brief Set your own snprintf function pointer * \brief This function allows configuring a custom \c snprintf function
* pointer.
* *
* \param snprintf_func the snprintf function implementation * \param snprintf_func The \c snprintf function implementation.
* *
* \return 0 * \return \c 0 on success.
*/ */
int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n, int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n,
const char * format, ... ) ); const char * format, ... ) );
@ -219,11 +221,12 @@ int mbedtls_platform_set_snprintf( int (*snprintf_func)( char * s, size_t n,
extern void (*mbedtls_exit)( int status ); extern void (*mbedtls_exit)( int status );
/** /**
* \brief Set your own exit function pointer * \brief This function allows configuring a custom \c exit function
* pointer.
* *
* \param exit_func the exit function implementation * \param exit_func The \c exit function implementation.
* *
* \return 0 * \return \c 0 on success.
*/ */
int mbedtls_platform_set_exit( void (*exit_func)( int status ) ); int mbedtls_platform_set_exit( void (*exit_func)( int status ) );
#else #else
@ -266,12 +269,13 @@ extern int (*mbedtls_nv_seed_read)( unsigned char *buf, size_t buf_len );
extern int (*mbedtls_nv_seed_write)( unsigned char *buf, size_t buf_len ); extern int (*mbedtls_nv_seed_write)( unsigned char *buf, size_t buf_len );
/** /**
* \brief Set your own seed file writing/reading functions * \brief This function allows configuring custom seed file writing and
* reading functions.
* *
* \param nv_seed_read_func the seed reading function implementation * \param nv_seed_read_func The seed reading function implementation.
* \param nv_seed_write_func the seed writing function implementation * \param nv_seed_write_func The seed writing function implementation.
* *
* \return 0 * \return \c 0 on success.
*/ */
int mbedtls_platform_set_nv_seed( int mbedtls_platform_set_nv_seed(
int (*nv_seed_read_func)( unsigned char *buf, size_t buf_len ), int (*nv_seed_read_func)( unsigned char *buf, size_t buf_len ),
@ -292,13 +296,13 @@ int mbedtls_platform_set_nv_seed(
#if !defined(MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT) #if !defined(MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT)
/** /**
* \brief Platform context structure * \brief The platform context structure.
* *
* \note This structure may be used to assist platform-specific * \note This structure may be used to assist platform-specific
* setup/teardown operations. * setup or teardown operations.
*/ */
typedef struct { typedef struct {
char dummy; /**< Placeholder member as empty structs are not portable */ char dummy; /**< Placeholder member, as empty structs are not portable. */
} }
mbedtls_platform_context; mbedtls_platform_context;
@ -307,32 +311,32 @@ mbedtls_platform_context;
#endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */ #endif /* !MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT */
/** /**
* \brief Perform any platform initialisation operations * \brief This function performs any platform initialization operations.
* *
* \param ctx mbed TLS context * \param ctx The Mbed TLS context.
* *
* \return 0 if successful * \return \c 0 on success.
* *
* \note This function is intended to allow platform specific initialisation, * \note This function is intended to allow platform-specific initialization,
* and should be called before any other library functions. Its * and should be called before any other library functions. Its
* implementation is platform specific, and by default, unless platform * implementation is platform-specific, and unless
* specific code is provided, it does nothing. * platform-specific code is provided, it does nothing.
* *
* Its use and whether its necessary to be called is dependent on the * Its use and whether it is necessary to call it is dependent on the
* platform. * platform.
*/ */
int mbedtls_platform_setup( mbedtls_platform_context *ctx ); int mbedtls_platform_setup( mbedtls_platform_context *ctx );
/** /**
* \brief Perform any platform teardown operations * \brief This function performs any platform teardown operations.
* *
* \param ctx mbed TLS context * \param ctx The Mbed TLS context.
* *
* \note This function should be called after every other mbed TLS module has * \note This function should be called after every other Mbed TLS module
* been correctly freed using the appropriate free function. * has been correctly freed using the appropriate free function.
* Its implementation is platform specific, and by default, unless * Its implementation is platform-specific, and unless
* platform specific code is provided, it does nothing. * platform-specific code is provided, it does nothing.
* *
* Its use and whether its necessary to be called is dependent on the * Its use and whether it is necessary to call it is dependent on the
* platform. * platform.
*/ */
void mbedtls_platform_teardown( mbedtls_platform_context *ctx ); void mbedtls_platform_teardown( mbedtls_platform_context *ctx );

1098
include/mbedtls/rsa.h
View File

File diff suppressed because it is too large Load Diff

100
include/mbedtls/sha1.h
View File

@ -1,10 +1,10 @@
/** /**
* \file sha1.h * \file sha1.h
* *
* \brief SHA-1 cryptographic hash function * \brief The SHA-1 cryptographic hash function.
*/ */
/* /*
* 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
@ -19,7 +19,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_SHA1_H #ifndef MBEDTLS_SHA1_H
#define MBEDTLS_SHA1_H #define MBEDTLS_SHA1_H
@ -49,68 +49,70 @@ extern "C" {
#endif #endif
/** /**
* \brief SHA-1 context structure * \brief The SHA-1 context structure.
*/ */
typedef struct typedef struct
{ {
uint32_t total[2]; /*!< number of bytes processed */ uint32_t total[2]; /*!< The number of Bytes processed. */
uint32_t state[5]; /*!< intermediate digest state */ uint32_t state[5]; /*!< The intermediate digest state. */
unsigned char buffer[64]; /*!< data block being processed */ unsigned char buffer[64]; /*!< The data block being processed. */
} }
mbedtls_sha1_context; mbedtls_sha1_context;
/** /**
* \brief Initialize SHA-1 context * \brief This function initializes a SHA-1 context.
* *
* \param ctx SHA-1 context to be initialized * \param ctx The SHA-1 context to initialize.
*/ */
void mbedtls_sha1_init( mbedtls_sha1_context *ctx ); void mbedtls_sha1_init( mbedtls_sha1_context *ctx );
/** /**
* \brief Clear SHA-1 context * \brief This function clears a SHA-1 context.
* *
* \param ctx SHA-1 context to be cleared * \param ctx The SHA-1 context to clear.
*/ */
void mbedtls_sha1_free( mbedtls_sha1_context *ctx ); void mbedtls_sha1_free( mbedtls_sha1_context *ctx );
/** /**
* \brief Clone (the state of) a SHA-1 context * \brief This function clones the state of a SHA-1 context.
* *
* \param dst The destination context * \param dst The destination context.
* \param src The context to be cloned * \param src The context to clone.
*/ */
void mbedtls_sha1_clone( mbedtls_sha1_context *dst, void mbedtls_sha1_clone( mbedtls_sha1_context *dst,
const mbedtls_sha1_context *src ); const mbedtls_sha1_context *src );
/** /**
* \brief SHA-1 context setup * \brief This function starts a SHA-1 checksum calculation.
* *
* \param ctx context to be initialized * \param ctx The context to initialize.
* *
* \return 0 if successful * \return \c 0 if successful
*/ */
int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx ); int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx );
/** /**
* \brief SHA-1 process buffer * \brief This function feeds an input buffer into an ongoing SHA-1
* checksum calculation.
* *
* \param ctx SHA-1 context * \param ctx The SHA-1 context.
* \param input buffer holding the data * \param input The buffer holding the input data.
* \param ilen length of the input data * \param ilen The length of the input data.
* *
* \return 0 if successful * \return \c 0 if successful
*/ */
int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx, int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
const unsigned char *input, const unsigned char *input,
size_t ilen ); size_t ilen );
/** /**
* \brief SHA-1 final digest * \brief This function finishes the SHA-1 operation, and writes
* the result to the output buffer.
* *
* \param ctx SHA-1 context * \param ctx The SHA-1 context.
* \param output SHA-1 checksum result * \param output The SHA-1 checksum result.
* *
* \return 0 if successful * \return \c 0 if successful
*/ */
int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx, int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
unsigned char output[20] ); unsigned char output[20] );
@ -119,9 +121,9 @@ int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
* \brief SHA-1 process data block (internal use only) * \brief SHA-1 process data block (internal use only)
* *
* \param ctx SHA-1 context * \param ctx SHA-1 context
* \param data buffer holding one block of data * \param data The data block being processed.
* *
* \return 0 if successful * \return \c 0 if successful
*/ */
int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx, int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
const unsigned char data[64] ); const unsigned char data[64] );
@ -137,7 +139,7 @@ int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
* *
* \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha1_starts_ret() in 2.7.0
* *
* \param ctx context to be initialized * \param ctx The SHA-1 context to be initialized.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha1_starts( MBEDTLS_DEPRECATED static inline void mbedtls_sha1_starts(
mbedtls_sha1_context *ctx ) mbedtls_sha1_context *ctx )
@ -150,9 +152,9 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_starts(
* *
* \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha1_update_ret() in 2.7.0
* *
* \param ctx SHA-1 context * \param ctx The SHA-1 context.
* \param input buffer holding the data * \param input The buffer holding the input data.
* \param ilen length of the input data * \param ilen The length of the input data.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha1_update( MBEDTLS_DEPRECATED static inline void mbedtls_sha1_update(
mbedtls_sha1_context *ctx, mbedtls_sha1_context *ctx,
@ -167,8 +169,8 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_update(
* *
* \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha1_finish_ret() in 2.7.0
* *
* \param ctx SHA-1 context * \param ctx The SHA-1 context.
* \param output SHA-1 checksum result * \param output The SHA-1 checksum result.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha1_finish( MBEDTLS_DEPRECATED static inline void mbedtls_sha1_finish(
mbedtls_sha1_context *ctx, mbedtls_sha1_context *ctx,
@ -182,8 +184,8 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_finish(
* *
* \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0 * \deprecated Superseded by mbedtls_internal_sha1_process() in 2.7.0
* *
* \param ctx SHA-1 context * \param ctx The SHA-1 context.
* \param data buffer holding one block of data * \param data The data block being processed.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha1_process( MBEDTLS_DEPRECATED static inline void mbedtls_sha1_process(
mbedtls_sha1_context *ctx, mbedtls_sha1_context *ctx,
@ -208,13 +210,19 @@ extern "C" {
#endif #endif
/** /**
* \brief Output = SHA-1( input buffer ) * \brief This function calculates the SHA-1 checksum of a buffer.
* *
* \param input buffer holding the data * The function allocates the context, performs the
* \param ilen length of the input data * calculation, and frees the context.
* \param output SHA-1 checksum result
* *
* \return 0 if successful * The SHA-1 result is calculated as
* output = SHA-1(input buffer).
*
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
* \param output The SHA-1 checksum result.
*
* \return \c 0 if successful
*/ */
int mbedtls_sha1_ret( const unsigned char *input, int mbedtls_sha1_ret( const unsigned char *input,
size_t ilen, size_t ilen,
@ -231,9 +239,9 @@ int mbedtls_sha1_ret( const unsigned char *input,
* *
* \deprecated Superseded by mbedtls_sha1_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha1_ret() in 2.7.0
* *
* \param input buffer holding the 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 SHA-1 checksum result * \param output The SHA-1 checksum result.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha1( const unsigned char *input, MBEDTLS_DEPRECATED static inline void mbedtls_sha1( const unsigned char *input,
size_t ilen, size_t ilen,
@ -246,9 +254,9 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha1( const unsigned char *input,
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
/** /**
* \brief Checkup routine * \brief The SHA-1 checkup routine.
* *
* \return 0 if successful, or 1 if the test failed * \return \c 0 on success, or \c 1 on failure.
*/ */
int mbedtls_sha1_self_test( int verbose ); int mbedtls_sha1_self_test( int verbose );

158
include/mbedtls/sha256.h
View File

@ -1,10 +1,10 @@
/** /**
* \file sha256.h * \file sha256.h
* *
* \brief SHA-224 and SHA-256 cryptographic hash function * \brief The SHA-224 and SHA-256 cryptographic hash function.
*/ */
/* /*
* 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
@ -19,7 +19,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_SHA256_H #ifndef MBEDTLS_SHA256_H
#define MBEDTLS_SHA256_H #define MBEDTLS_SHA256_H
@ -39,7 +39,6 @@
!defined(inline) && !defined(__cplusplus) !defined(inline) && !defined(__cplusplus)
#define inline __inline #define inline __inline
#endif #endif
#if !defined(MBEDTLS_SHA256_ALT) #if !defined(MBEDTLS_SHA256_ALT)
// Regular implementation // Regular implementation
// //
@ -49,81 +48,94 @@ extern "C" {
#endif #endif
/** /**
* \brief SHA-256 context structure * \brief The SHA-256 context structure.
*
* The structure is used both for SHA-256 and for SHA-224
* checksum calculations. The choice between these two is
* made in the call to mbedtls_sha256_starts_ret().
*/ */
typedef struct typedef struct
{ {
uint32_t total[2]; /*!< number of bytes processed */ uint32_t total[2]; /*!< The number of Bytes processed. */
uint32_t state[8]; /*!< intermediate digest state */ uint32_t state[8]; /*!< The intermediate digest state. */
unsigned char buffer[64]; /*!< data block being processed */ unsigned char buffer[64]; /*!< The data block being processed. */
int is224; /*!< 0 => SHA-256, else SHA-224 */ int is224; /*!< Determines which function to use.
<ul><li>0: Use SHA-256.</li>
<li>1: Use SHA-224.</li></ul> */
} }
mbedtls_sha256_context; mbedtls_sha256_context;
/** /**
* \brief Initialize SHA-256 context * \brief This function initializes a SHA-256 context.
* *
* \param ctx SHA-256 context to be initialized * \param ctx The SHA-256 context to initialize.
*/ */
void mbedtls_sha256_init( mbedtls_sha256_context *ctx ); void mbedtls_sha256_init( mbedtls_sha256_context *ctx );
/** /**
* \brief Clear SHA-256 context * \brief This function clears a SHA-256 context.
* *
* \param ctx SHA-256 context to be cleared * \param ctx The SHA-256 context to clear.
*/ */
void mbedtls_sha256_free( mbedtls_sha256_context *ctx ); void mbedtls_sha256_free( mbedtls_sha256_context *ctx );
/** /**
* \brief Clone (the state of) a SHA-256 context * \brief This function clones the state of a SHA-256 context.
* *
* \param dst The destination context * \param dst The destination context.
* \param src The context to be cloned * \param src The context to clone.
*/ */
void mbedtls_sha256_clone( mbedtls_sha256_context *dst, void mbedtls_sha256_clone( mbedtls_sha256_context *dst,
const mbedtls_sha256_context *src ); const mbedtls_sha256_context *src );
/** /**
* \brief SHA-256 context setup * \brief This function starts a SHA-224 or SHA-256 checksum
* calculation.
* *
* \param ctx context to be initialized * \param ctx The context to initialize.
* \param is224 0 = use SHA256, 1 = use SHA224 * \param is224 Determines which function to use.
* <ul><li>0: Use SHA-256.</li>
* <li>1: Use SHA-224.</li></ul>
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 ); int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 );
/** /**
* \brief SHA-256 process buffer * \brief This function feeds an input buffer into an ongoing
* SHA-256 checksum calculation.
* *
* \param ctx SHA-256 context * \param ctx SHA-256 context
* \param input buffer holding the data * \param input buffer holding the data
* \param ilen length of the input data * \param ilen length of the input data
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx, int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx,
const unsigned char *input, const unsigned char *input,
size_t ilen ); size_t ilen );
/** /**
* \brief SHA-256 final digest * \brief This function finishes the SHA-256 operation, and writes
* the result to the output buffer.
* *
* \param ctx SHA-256 context * \param ctx The SHA-256 context.
* \param output SHA-224/256 checksum result * \param output The SHA-224 or SHA-256 checksum result.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx, int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx,
unsigned char output[32] ); unsigned char output[32] );
/** /**
* \brief SHA-256 process data block (internal use only) * \brief This function processes a single data block within
* the ongoing SHA-256 computation. This function is for
* internal use only.
* *
* \param ctx SHA-256 context * \param ctx The SHA-256 context.
* \param data buffer holding one block of data * \param data The buffer holding one block of data.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx, int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
const unsigned char data[64] ); const unsigned char data[64] );
@ -135,12 +147,14 @@ int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief SHA-256 context setup * \brief This function starts a SHA-256 checksum calculation.
* *
* \deprecated Superseded by mbedtls_sha256_starts_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha256_starts_ret() in 2.7.0.
* *
* \param ctx context to be initialized * \param ctx The SHA-256 context to initialize.
* \param is224 0 = use SHA256, 1 = use SHA224 * \param is224 Determines which function to use.
* <ul><li>0: Use SHA-256.</li>
* <li>1: Use SHA-224.</li></ul>
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha256_starts( MBEDTLS_DEPRECATED static inline void mbedtls_sha256_starts(
mbedtls_sha256_context *ctx, mbedtls_sha256_context *ctx,
@ -150,13 +164,14 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha256_starts(
} }
/** /**
* \brief SHA-256 process buffer * \brief This function feeds an input buffer into an ongoing
* SHA-256 checksum calculation.
* *
* \deprecated Superseded by mbedtls_sha256_update_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha256_update_ret() in 2.7.0.
* *
* \param ctx SHA-256 context * \param ctx The SHA-256 context to initialize.
* \param input buffer holding the data * \param input The buffer holding the data.
* \param ilen length of the input data * \param ilen The length of the input data.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha256_update( MBEDTLS_DEPRECATED static inline void mbedtls_sha256_update(
mbedtls_sha256_context *ctx, mbedtls_sha256_context *ctx,
@ -167,12 +182,13 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha256_update(
} }
/** /**
* \brief SHA-256 final digest * \brief This function finishes the SHA-256 operation, and writes
* the result to the output buffer.
* *
* \deprecated Superseded by mbedtls_sha256_finish_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha256_finish_ret() in 2.7.0.
* *
* \param ctx SHA-256 context * \param ctx The SHA-256 context.
* \param output SHA-224/256 checksum result * \param output The SHA-224or SHA-256 checksum result.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha256_finish( MBEDTLS_DEPRECATED static inline void mbedtls_sha256_finish(
mbedtls_sha256_context *ctx, mbedtls_sha256_context *ctx,
@ -182,12 +198,14 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha256_finish(
} }
/** /**
* \brief SHA-256 process data block (internal use only) * \brief This function processes a single data block within
* the ongoing SHA-256 computation. This function is for
* internal use only.
* *
* \deprecated Superseded by mbedtls_internal_sha256_process() in 2.7.0 * \deprecated Superseded by mbedtls_internal_sha256_process() in 2.7.0.
* *
* \param ctx SHA-256 context * \param ctx The SHA-256 context.
* \param data buffer holding one block of data * \param data The buffer holding one block of data.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha256_process( MBEDTLS_DEPRECATED static inline void mbedtls_sha256_process(
mbedtls_sha256_context *ctx, mbedtls_sha256_context *ctx,
@ -198,7 +216,6 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha256_process(
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
@ -212,14 +229,21 @@ extern "C" {
#endif #endif
/** /**
* \brief Output = SHA-256( input buffer ) * \brief This function calculates the SHA-224 or SHA-256
* checksum of a buffer.
* *
* \param input buffer holding the data * The function allocates the context, performs the
* \param ilen length of the input data * calculation, and frees the context.
* \param output SHA-224/256 checksum result
* \param is224 0 = use SHA256, 1 = use SHA224
* *
* \return 0 if successful * The SHA-256 result is calculated as
* output = SHA-256(input buffer).
*
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
* \param output The SHA-224 or SHA-256 checksum result.
* \param is224 Determines which function to use.
* <ul><li>0: Use SHA-256.</li>
* <li>1: Use SHA-224.</li></ul>
*/ */
int mbedtls_sha256_ret( const unsigned char *input, int mbedtls_sha256_ret( const unsigned char *input,
size_t ilen, size_t ilen,
@ -232,15 +256,25 @@ int mbedtls_sha256_ret( const unsigned char *input,
#else #else
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief Output = SHA-256( input buffer ) * \brief This function calculates the SHA-224 or SHA-256 checksum
* of a buffer.
* *
* \deprecated Superseded by mbedtls_sha256_ret() in 2.7.0 * The function allocates the context, performs the
* calculation, and frees the context.
* *
* \param input buffer holding the data * The SHA-256 result is calculated as
* \param ilen length of the input data * output = SHA-256(input buffer).
* \param output SHA-224/256 checksum result *
* \param is224 0 = use SHA256, 1 = use SHA224 * \deprecated Superseded by mbedtls_sha256_ret() in 2.7.0.
*
* \param input The buffer holding the data.
* \param ilen The length of the input data.
* \param output The SHA-224 or SHA-256 checksum result.
* \param is224 Determines which function to use.
* <ul><li>0: Use SHA-256.</li>
* <li>1: Use SHA-224.</li></ul>
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha256( MBEDTLS_DEPRECATED static inline void mbedtls_sha256(
const unsigned char *input, const unsigned char *input,
@ -255,9 +289,9 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha256(
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
/** /**
* \brief Checkup routine * \brief The SHA-224 and SHA-256 checkup routine.
* *
* \return 0 if successful, or 1 if the test failed * \return \c 0 on success, or \c 1 on failure.
*/ */
int mbedtls_sha256_self_test( int verbose ); int mbedtls_sha256_self_test( int verbose );

163
include/mbedtls/sha512.h
View File

@ -1,10 +1,10 @@
/** /**
* \file sha512.h * \file sha512.h
* *
* \brief SHA-384 and SHA-512 cryptographic hash function * \brief The SHA-384 and SHA-512 cryptographic hash function.
*/ */
/* /*
* 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
@ -19,7 +19,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_SHA512_H #ifndef MBEDTLS_SHA512_H
#define MBEDTLS_SHA512_H #define MBEDTLS_SHA512_H
@ -39,7 +39,6 @@
!defined(inline) && !defined(__cplusplus) !defined(inline) && !defined(__cplusplus)
#define inline __inline #define inline __inline
#endif #endif
#if !defined(MBEDTLS_SHA512_ALT) #if !defined(MBEDTLS_SHA512_ALT)
// Regular implementation // Regular implementation
// //
@ -49,85 +48,97 @@ extern "C" {
#endif #endif
/** /**
* \brief SHA-512 context structure * \brief The SHA-512 context structure.
*
* The structure is used both for SHA-384 and for SHA-512
* checksum calculations. The choice between these two is
* made in the call to mbedtls_sha512_starts_ret().
*/ */
typedef struct typedef struct
{ {
uint64_t total[2]; /*!< number of bytes processed */ uint64_t total[2]; /*!< The number of Bytes processed. */
uint64_t state[8]; /*!< intermediate digest state */ uint64_t state[8]; /*!< The intermediate digest state. */
unsigned char buffer[128]; /*!< data block being processed */ unsigned char buffer[128]; /*!< The data block being processed. */
int is384; /*!< 0 => SHA-512, else SHA-384 */ int is384; /*!< Determines which function to use.
* <ul><li>0: Use SHA-512.</li>
* <li>1: Use SHA-384.</li></ul> */
} }
mbedtls_sha512_context; mbedtls_sha512_context;
/** /**
* \brief Initialize SHA-512 context * \brief This function initializes a SHA-512 context.
* *
* \param ctx SHA-512 context to be initialized * \param ctx The SHA-512 context to initialize.
*/ */
void mbedtls_sha512_init( mbedtls_sha512_context *ctx ); void mbedtls_sha512_init( mbedtls_sha512_context *ctx );
/** /**
* \brief Clear SHA-512 context * \brief This function clears a SHA-512 context.
* *
* \param ctx SHA-512 context to be cleared * \param ctx The SHA-512 context to clear.
*/ */
void mbedtls_sha512_free( mbedtls_sha512_context *ctx ); void mbedtls_sha512_free( mbedtls_sha512_context *ctx );
/** /**
* \brief Clone (the state of) a SHA-512 context * \brief This function clones the state of a SHA-512 context.
* *
* \param dst The destination context * \param dst The destination context.
* \param src The context to be cloned * \param src The context to clone.
*/ */
void mbedtls_sha512_clone( mbedtls_sha512_context *dst, void mbedtls_sha512_clone( mbedtls_sha512_context *dst,
const mbedtls_sha512_context *src ); const mbedtls_sha512_context *src );
/** /**
* \brief SHA-512 context setup * \brief This function starts a SHA-384 or SHA-512 checksum
* calculation.
* *
* \param ctx context to be initialized * \param ctx The SHA-512 context to initialize.
* \param is384 0 = use SHA512, 1 = use SHA384 * \param is384 Determines which function to use.
* <ul><li>0: Use SHA-512.</li>
* <li>1: Use SHA-384.</li></ul>
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 ); int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 );
/** /**
* \brief SHA-512 process buffer * \brief This function feeds an input buffer into an ongoing
* SHA-512 checksum calculation.
* *
* \param ctx SHA-512 context * \param ctx The SHA-512 context.
* \param input buffer holding the data * \param input The buffer holding the input data.
* \param ilen length of the input data * \param ilen The length of the input data.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx, int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
const unsigned char *input, const unsigned char *input,
size_t ilen ); size_t ilen );
/** /**
* \brief SHA-512 final digest * \brief This function finishes the SHA-512 operation, and writes
* the result to the output buffer. This function is for
* internal use only.
* *
* \param ctx SHA-512 context * \param ctx The SHA-512 context.
* \param output SHA-384/512 checksum result * \param output The SHA-384 or SHA-512 checksum result.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx, int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
unsigned char output[64] ); unsigned char output[64] );
/** /**
* \brief SHA-512 process data block (internal use only) * \brief This function processes a single data block within
* the ongoing SHA-512 computation.
* *
* \param ctx SHA-512 context * \param ctx The SHA-512 context.
* \param data buffer holding one block of data * \param data The buffer holding one block of data.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx, int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
const unsigned char data[128] ); const unsigned char data[128] );
#if !defined(MBEDTLS_DEPRECATED_REMOVED) #if !defined(MBEDTLS_DEPRECATED_REMOVED)
#if defined(MBEDTLS_DEPRECATED_WARNING) #if defined(MBEDTLS_DEPRECATED_WARNING)
#define MBEDTLS_DEPRECATED __attribute__((deprecated)) #define MBEDTLS_DEPRECATED __attribute__((deprecated))
@ -135,12 +146,15 @@ int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief SHA-512 context setup * \brief This function starts a SHA-384 or SHA-512 checksum
* calculation.
* *
* \deprecated Superseded by mbedtls_sha512_starts_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha512_starts_ret() in 2.7.0
* *
* \param ctx context to be initialized * \param ctx The SHA-512 context to initialize.
* \param is384 0 = use SHA512, 1 = use SHA384 * \param is384 Determines which function to use.
* <ul><li>0: Use SHA-512.</li>
* <li>1: Use SHA-384.</li></ul>
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha512_starts( MBEDTLS_DEPRECATED static inline void mbedtls_sha512_starts(
mbedtls_sha512_context *ctx, mbedtls_sha512_context *ctx,
@ -150,13 +164,14 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_starts(
} }
/** /**
* \brief SHA-512 process buffer * \brief This function feeds an input buffer into an ongoing
* SHA-512 checksum calculation.
* *
* \deprecated Superseded by mbedtls_sha512_update_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha512_update_ret() in 2.7.0
* *
* \param ctx SHA-512 context * \param ctx The SHA-512 context.
* \param input buffer holding the data * \param input The buffer holding the data.
* \param ilen length of the input data * \param ilen The length of the input data.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha512_update( MBEDTLS_DEPRECATED static inline void mbedtls_sha512_update(
mbedtls_sha512_context *ctx, mbedtls_sha512_context *ctx,
@ -167,12 +182,13 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_update(
} }
/** /**
* \brief SHA-512 final digest * \brief This function finishes the SHA-512 operation, and writes
* the result to the output buffer.
* *
* \deprecated Superseded by mbedtls_sha512_finish_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha512_finish_ret() in 2.7.0
* *
* \param ctx SHA-512 context * \param ctx The SHA-512 context.
* \param output SHA-384/512 checksum result * \param output The SHA-384 or SHA-512 checksum result.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha512_finish( MBEDTLS_DEPRECATED static inline void mbedtls_sha512_finish(
mbedtls_sha512_context *ctx, mbedtls_sha512_context *ctx,
@ -182,12 +198,14 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_finish(
} }
/** /**
* \brief SHA-512 process data block (internal use only) * \brief This function processes a single data block within
* the ongoing SHA-512 computation. This function is for
* internal use only.
* *
* \deprecated Superseded by mbedtls_internal_sha512_process() in 2.7.0 * \deprecated Superseded by mbedtls_internal_sha512_process() in 2.7.0
* *
* \param ctx SHA-512 context * \param ctx The SHA-512 context.
* \param data buffer holding one block of data * \param data The buffer holding one block of data.
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha512_process( MBEDTLS_DEPRECATED static inline void mbedtls_sha512_process(
mbedtls_sha512_context *ctx, mbedtls_sha512_context *ctx,
@ -212,14 +230,23 @@ extern "C" {
#endif #endif
/** /**
* \brief Output = SHA-512( input buffer ) * \brief This function calculates the SHA-512 or SHA-384
* checksum of a buffer.
* *
* \param input buffer holding the data * The function allocates the context, performs the
* \param ilen length of the input data * calculation, and frees the context.
* \param output SHA-384/512 checksum result
* \param is384 0 = use SHA512, 1 = use SHA384
* *
* \return 0 if successful * The SHA-512 result is calculated as
* output = SHA-512(input buffer).
*
* \param input The buffer holding the input data.
* \param ilen The length of the input data.
* \param output The SHA-384 or SHA-512 checksum result.
* \param is384 Determines which function to use.
* <ul><li>0: Use SHA-512.</li>
* <li>1: Use SHA-384.</li></ul>
*
* \return \c 0 on success.
*/ */
int mbedtls_sha512_ret( const unsigned char *input, int mbedtls_sha512_ret( const unsigned char *input,
size_t ilen, size_t ilen,
@ -233,14 +260,23 @@ int mbedtls_sha512_ret( const unsigned char *input,
#define MBEDTLS_DEPRECATED #define MBEDTLS_DEPRECATED
#endif #endif
/** /**
* \brief Output = SHA-512( input buffer ) * \brief This function calculates the SHA-512 or SHA-384
* checksum of a buffer.
*
* The function allocates the context, performs the
* calculation, and frees the context.
*
* The SHA-512 result is calculated as
* output = SHA-512(input buffer).
* *
* \deprecated Superseded by mbedtls_sha512_ret() in 2.7.0 * \deprecated Superseded by mbedtls_sha512_ret() in 2.7.0
* *
* \param input buffer holding the data * \param input The buffer holding the data.
* \param ilen length of the input data * \param ilen The length of the input data.
* \param output SHA-384/512 checksum result * \param output The SHA-384 or SHA-512 checksum result.
* \param is384 0 = use SHA512, 1 = use SHA384 * \param is384 Determines which function to use.
* <ul><li>0: Use SHA-512.</li>
* <li>1: Use SHA-384.</li></ul>
*/ */
MBEDTLS_DEPRECATED static inline void mbedtls_sha512( MBEDTLS_DEPRECATED static inline void mbedtls_sha512(
const unsigned char *input, const unsigned char *input,
@ -253,11 +289,10 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha512(
#undef MBEDTLS_DEPRECATED #undef MBEDTLS_DEPRECATED
#endif /* !MBEDTLS_DEPRECATED_REMOVED */ #endif /* !MBEDTLS_DEPRECATED_REMOVED */
/**
/** * \brief The SHA-384 or SHA-512 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_sha512_self_test( int verbose ); int mbedtls_sha512_self_test( int verbose );

22
library/error.c
View File

@ -210,7 +210,7 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen )
if( use_ret == -(MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE) ) if( use_ret == -(MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE) )
mbedtls_snprintf( buf, buflen, "CIPHER - The selected feature is not available" ); mbedtls_snprintf( buf, buflen, "CIPHER - The selected feature is not available" );
if( use_ret == -(MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA) ) if( use_ret == -(MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA) )
mbedtls_snprintf( buf, buflen, "CIPHER - Bad input parameters to function" ); mbedtls_snprintf( buf, buflen, "CIPHER - Bad input parameters" );
if( use_ret == -(MBEDTLS_ERR_CIPHER_ALLOC_FAILED) ) if( use_ret == -(MBEDTLS_ERR_CIPHER_ALLOC_FAILED) )
mbedtls_snprintf( buf, buflen, "CIPHER - Failed to allocate memory" ); mbedtls_snprintf( buf, buflen, "CIPHER - Failed to allocate memory" );
if( use_ret == -(MBEDTLS_ERR_CIPHER_INVALID_PADDING) ) if( use_ret == -(MBEDTLS_ERR_CIPHER_INVALID_PADDING) )
@ -220,14 +220,14 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen )
if( use_ret == -(MBEDTLS_ERR_CIPHER_AUTH_FAILED) ) if( use_ret == -(MBEDTLS_ERR_CIPHER_AUTH_FAILED) )
mbedtls_snprintf( buf, buflen, "CIPHER - Authentication failed (for AEAD modes)" ); mbedtls_snprintf( buf, buflen, "CIPHER - Authentication failed (for AEAD modes)" );
if( use_ret == -(MBEDTLS_ERR_CIPHER_INVALID_CONTEXT) ) if( use_ret == -(MBEDTLS_ERR_CIPHER_INVALID_CONTEXT) )
mbedtls_snprintf( buf, buflen, "CIPHER - The context is invalid, eg because it was free()ed" ); mbedtls_snprintf( buf, buflen, "CIPHER - The context is invalid. For example, because it was freed" );
if( use_ret == -(MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED) ) if( use_ret == -(MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED) )
mbedtls_snprintf( buf, buflen, "CIPHER - Cipher hardware accelerator failed" ); mbedtls_snprintf( buf, buflen, "CIPHER - Cipher hardware accelerator failed" );
#endif /* MBEDTLS_CIPHER_C */ #endif /* MBEDTLS_CIPHER_C */
#if defined(MBEDTLS_DHM_C) #if defined(MBEDTLS_DHM_C)
if( use_ret == -(MBEDTLS_ERR_DHM_BAD_INPUT_DATA) ) if( use_ret == -(MBEDTLS_ERR_DHM_BAD_INPUT_DATA) )
mbedtls_snprintf( buf, buflen, "DHM - Bad input parameters to function" ); mbedtls_snprintf( buf, buflen, "DHM - Bad input parameters" );
if( use_ret == -(MBEDTLS_ERR_DHM_READ_PARAMS_FAILED) ) if( use_ret == -(MBEDTLS_ERR_DHM_READ_PARAMS_FAILED) )
mbedtls_snprintf( buf, buflen, "DHM - Reading of the DHM parameters failed" ); mbedtls_snprintf( buf, buflen, "DHM - Reading of the DHM parameters failed" );
if( use_ret == -(MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED) ) if( use_ret == -(MBEDTLS_ERR_DHM_MAKE_PARAMS_FAILED) )
@ -243,7 +243,7 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen )
if( use_ret == -(MBEDTLS_ERR_DHM_ALLOC_FAILED) ) if( use_ret == -(MBEDTLS_ERR_DHM_ALLOC_FAILED) )
mbedtls_snprintf( buf, buflen, "DHM - Allocation of memory failed" ); mbedtls_snprintf( buf, buflen, "DHM - Allocation of memory failed" );
if( use_ret == -(MBEDTLS_ERR_DHM_FILE_IO_ERROR) ) if( use_ret == -(MBEDTLS_ERR_DHM_FILE_IO_ERROR) )
mbedtls_snprintf( buf, buflen, "DHM - Read/write of file failed" ); mbedtls_snprintf( buf, buflen, "DHM - Read or write of file failed" );
if( use_ret == -(MBEDTLS_ERR_DHM_HW_ACCEL_FAILED) ) if( use_ret == -(MBEDTLS_ERR_DHM_HW_ACCEL_FAILED) )
mbedtls_snprintf( buf, buflen, "DHM - DHM hardware accelerator failed" ); mbedtls_snprintf( buf, buflen, "DHM - DHM hardware accelerator failed" );
if( use_ret == -(MBEDTLS_ERR_DHM_SET_GROUP_FAILED) ) if( use_ret == -(MBEDTLS_ERR_DHM_SET_GROUP_FAILED) )
@ -368,7 +368,7 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen )
if( use_ret == -(MBEDTLS_ERR_RSA_KEY_GEN_FAILED) ) if( use_ret == -(MBEDTLS_ERR_RSA_KEY_GEN_FAILED) )
mbedtls_snprintf( buf, buflen, "RSA - Something failed during generation of a key" ); mbedtls_snprintf( buf, buflen, "RSA - Something failed during generation of a key" );
if( use_ret == -(MBEDTLS_ERR_RSA_KEY_CHECK_FAILED) ) if( use_ret == -(MBEDTLS_ERR_RSA_KEY_CHECK_FAILED) )
mbedtls_snprintf( buf, buflen, "RSA - Key failed to pass the library's validity check" ); mbedtls_snprintf( buf, buflen, "RSA - Key failed to pass the validity check of the library" );
if( use_ret == -(MBEDTLS_ERR_RSA_PUBLIC_FAILED) ) if( use_ret == -(MBEDTLS_ERR_RSA_PUBLIC_FAILED) )
mbedtls_snprintf( buf, buflen, "RSA - The public key operation failed" ); mbedtls_snprintf( buf, buflen, "RSA - The public key operation failed" );
if( use_ret == -(MBEDTLS_ERR_RSA_PRIVATE_FAILED) ) if( use_ret == -(MBEDTLS_ERR_RSA_PRIVATE_FAILED) )
@ -380,7 +380,7 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen )
if( use_ret == -(MBEDTLS_ERR_RSA_RNG_FAILED) ) if( use_ret == -(MBEDTLS_ERR_RSA_RNG_FAILED) )
mbedtls_snprintf( buf, buflen, "RSA - The random generator failed to generate non-zeros" ); mbedtls_snprintf( buf, buflen, "RSA - The random generator failed to generate non-zeros" );
if( use_ret == -(MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION) ) if( use_ret == -(MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION) )
mbedtls_snprintf( buf, buflen, "RSA - The implementation doesn't offer the requested operation, e.g. because of security violations or lack of functionality" ); mbedtls_snprintf( buf, buflen, "RSA - The implementation does not offer the requested operation, for example, because of security violations or lack of functionality" );
if( use_ret == -(MBEDTLS_ERR_RSA_HW_ACCEL_FAILED) ) if( use_ret == -(MBEDTLS_ERR_RSA_HW_ACCEL_FAILED) )
mbedtls_snprintf( buf, buflen, "RSA - RSA hardware accelerator failed" ); mbedtls_snprintf( buf, buflen, "RSA - RSA hardware accelerator failed" );
#endif /* MBEDTLS_RSA_C */ #endif /* MBEDTLS_RSA_C */
@ -571,7 +571,7 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen )
if( use_ret == -(MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH) ) if( use_ret == -(MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH) )
mbedtls_snprintf( buf, buflen, "AES - Invalid data input length" ); mbedtls_snprintf( buf, buflen, "AES - Invalid data input length" );
if( use_ret == -(MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE) ) if( use_ret == -(MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE) )
mbedtls_snprintf( buf, buflen, "AES - Feature not available, e.g. unsupported AES key size" ); mbedtls_snprintf( buf, buflen, "AES - Feature not available. For example, an unsupported AES key size" );
if( use_ret == -(MBEDTLS_ERR_AES_HW_ACCEL_FAILED) ) if( use_ret == -(MBEDTLS_ERR_AES_HW_ACCEL_FAILED) )
mbedtls_snprintf( buf, buflen, "AES - AES hardware accelerator failed" ); mbedtls_snprintf( buf, buflen, "AES - AES hardware accelerator failed" );
#endif /* MBEDTLS_AES_C */ #endif /* MBEDTLS_AES_C */
@ -644,7 +644,7 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen )
#if defined(MBEDTLS_CCM_C) #if defined(MBEDTLS_CCM_C)
if( use_ret == -(MBEDTLS_ERR_CCM_BAD_INPUT) ) if( use_ret == -(MBEDTLS_ERR_CCM_BAD_INPUT) )
mbedtls_snprintf( buf, buflen, "CCM - Bad input parameters to function" ); mbedtls_snprintf( buf, buflen, "CCM - Bad input parameters to the function" );
if( use_ret == -(MBEDTLS_ERR_CCM_AUTH_FAILED) ) if( use_ret == -(MBEDTLS_ERR_CCM_AUTH_FAILED) )
mbedtls_snprintf( buf, buflen, "CCM - Authenticated decryption failed" ); mbedtls_snprintf( buf, buflen, "CCM - Authenticated decryption failed" );
if( use_ret == -(MBEDTLS_ERR_CCM_HW_ACCEL_FAILED) ) if( use_ret == -(MBEDTLS_ERR_CCM_HW_ACCEL_FAILED) )
@ -660,11 +660,11 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen )
if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED) ) if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED) )
mbedtls_snprintf( buf, buflen, "CTR_DRBG - The entropy source failed" ); mbedtls_snprintf( buf, buflen, "CTR_DRBG - The entropy source failed" );
if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG) ) if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG) )
mbedtls_snprintf( buf, buflen, "CTR_DRBG - Too many random requested in single call" ); mbedtls_snprintf( buf, buflen, "CTR_DRBG - The requested random buffer length is too big" );
if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG) ) if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG) )
mbedtls_snprintf( buf, buflen, "CTR_DRBG - Input too large (Entropy + additional)" ); mbedtls_snprintf( buf, buflen, "CTR_DRBG - The input (entropy + additional data) is too large" );
if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR) ) if( use_ret == -(MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR) )
mbedtls_snprintf( buf, buflen, "CTR_DRBG - Read/write error in file" ); mbedtls_snprintf( buf, buflen, "CTR_DRBG - Read or write error in file" );
#endif /* MBEDTLS_CTR_DRBG_C */ #endif /* MBEDTLS_CTR_DRBG_C */
#if defined(MBEDTLS_DES_C) #if defined(MBEDTLS_DES_C)