diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index d5b3abe750..40fa056d85 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -165,7 +165,7 @@ SHORT_NAMES = NO # comments will behave just like regular Qt-style comments # (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 # interpret the first line (until the first dot) of a Qt-style diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h index 541fa930d5..46016dcb7f 100644 --- a/include/mbedtls/aes.h +++ b/include/mbedtls/aes.h @@ -1,10 +1,18 @@ /** * \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 + * FIPS Publication 197: Advanced Encryption Standard and + * ISO/IEC 18033-2:2006: Information technology -- Security + * techniques -- Encryption algorithms -- Part 2: Asymmetric + * ciphers. */ -/* - * 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 * * 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 * 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 #define MBEDTLS_AES_H @@ -34,15 +43,15 @@ #include /* padlock.c and aesni.c rely on these values! */ -#define MBEDTLS_AES_ENCRYPT 1 -#define MBEDTLS_AES_DECRYPT 0 +#define MBEDTLS_AES_ENCRYPT 1 /**< AES encryption. */ +#define MBEDTLS_AES_DECRYPT 0 /**< AES decryption. */ /* Error codes in range 0x0020-0x0022 */ #define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH -0x0020 /**< Invalid key length. */ #define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH -0x0022 /**< Invalid data input length. */ /* 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. */ #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \ @@ -59,68 +68,90 @@ extern "C" { #endif /** - * \brief AES context structure - * - * \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 + * \brief The AES context-type definition. */ typedef struct { - int nr; /*!< number of rounds */ - uint32_t *rk; /*!< AES round keys */ - uint32_t buf[68]; /*!< unaligned data */ + int nr; /*!< The number of rounds. */ + uint32_t *rk; /*!< AES round keys. */ + uint32_t buf[68]; /*!< Unaligned data buffer. This buffer can + hold 32 extra Bytes, which can be used for + one of the following purposes: + */ } 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 ); /** - * \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 ); /** - * \brief AES key schedule (encryption) + * \brief This function sets the encryption key. * - * \param ctx AES context to be initialized - * \param key encryption key - * \param keybits must be 128, 192 or 256 + * \param ctx The AES context to which the key should be bound. + * \param key The encryption key. + * \param keybits The size of data passed in bits. Valid options are: + * * - * \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, unsigned int keybits ); /** - * \brief AES key schedule (decryption) + * \brief This function sets the decryption key. * - * \param ctx AES context to be initialized - * \param key decryption key - * \param keybits must be 128, 192 or 256 + * \param ctx The AES context to which the key should be bound. + * \param key The decryption key. + * \param keybits The size of data passed. Valid options are: + * * - * \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, unsigned int keybits ); /** - * \brief AES-ECB block encryption/decryption + * \brief This function performs an AES single-block encryption or + * decryption operation. * - * \param ctx AES context - * \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT - * \param input 16-byte input block - * \param output 16-byte output block + * It performs the operation defined in the \p mode parameter + * (encrypt or decrypt), on the input data buffer defined in + * the \p input parameter. * - * \return 0 if successful + * mbedtls_aes_init(), and either mbedtls_aes_setkey_enc() or + * mbedtls_aes_setkey_dec() must be called before the first + * call to this API with the same context. + * + * \param ctx The AES context to use for encryption or decryption. + * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or + * #MBEDTLS_AES_DECRYPT. + * \param input The 16-Byte buffer holding the input data. + * \param output The 16-Byte buffer holding the output data. + + * \return \c 0 on success. */ int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx, int mode, @@ -129,26 +160,40 @@ int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx, #if defined(MBEDTLS_CIPHER_MODE_CBC) /** - * \brief AES-CBC buffer encryption/decryption - * Length should be a multiple of the block - * size (16 bytes) + * \brief This function performs an AES-CBC encryption or decryption operation + * on full blocks. * - * \note Upon exit, the content of the IV is updated so that you can - * call the function same function again on the following - * block(s) of data and get the same result as if it was - * 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. + * It performs the operation defined in the \p mode + * parameter (encrypt/decrypt), on the input data buffer defined in + * the \p input parameter. * - * \param ctx AES context - * \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT - * \param length length of the input data - * \param iv initialization vector (updated after use) - * \param input buffer holding the input data - * \param output buffer holding the output data + * It can be called as many times as needed, until all the input + * data is processed. mbedtls_aes_init(), and either + * mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called + * before the first call to this API with the same context. * - * \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 mode, @@ -160,29 +205,38 @@ int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx, #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 - * both encryption and decryption. So a context initialized with - * mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. + * It performs the operation defined in the \p mode + * parameter (encrypt or decrypt), on the input data buffer + * defined in the \p input parameter. * - * \note Upon exit, the content of the IV is updated so that you can - * call the function same function again on the following - * block(s) of data and get the same result as if it was - * 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. + * For CFB, you must set up the context with mbedtls_aes_setkey_enc(), + * regardless of whether you are performing an encryption or decryption + * operation, that is, regardless of the \p mode parameter. This is + * because CFB mode uses the same key schedule for encryption and + * decryption. * - * \param ctx AES context - * \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT - * \param length length of the input data - * \param iv_off offset in IV (updated after use) - * \param iv initialization vector (updated after use) - * \param input buffer holding the input data - * \param output buffer holding the output data + * \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 must 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_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 mode, @@ -193,28 +247,36 @@ int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx, 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 - * both encryption and decryption. So a context initialized with - * mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. + * It performs the operation defined in the \p mode + * parameter (encrypt/decrypt), on the input data buffer defined + * in the \p input parameter. * - * \note Upon exit, the content of the IV is updated so that you can - * call the function same function again on the following - * block(s) of data and get the same result as if it was - * 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. + * Due to the nature of CFB, you must use the same key schedule for + * both encryption and decryption operations. Therefore, you must + * use the context initialized with mbedtls_aes_setkey_enc() for + * both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT. * - * \param ctx AES context - * \param mode MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT - * \param length length of the input data - * \param iv initialization vector (updated after use) - * \param input buffer holding the input data - * \param output buffer holding the output data + * \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. * - * \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 mode, @@ -226,26 +288,32 @@ int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx, #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 - * both encryption and decryption. So a context initialized with - * mbedtls_aes_setkey_enc() for both MBEDTLS_AES_ENCRYPT and MBEDTLS_AES_DECRYPT. + * Due to the nature of CTR, you must use the same key schedule + * for both encryption and decryption operations. Therefore, you + * must use the context initialized with mbedtls_aes_setkey_enc() + * for both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT. * - * \param ctx AES context - * \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 + * \warning You must keep the maximum use of your counter in mind. * - * \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, size_t length, @@ -257,30 +325,30 @@ int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx, #endif /* MBEDTLS_CIPHER_MODE_CTR */ /** - * \brief Internal AES block encryption function - * (Only exposed to allow overriding it, - * see MBEDTLS_AES_ENCRYPT_ALT) + * \brief Internal AES block encryption function. This is only + * exposed to allow overriding it using + * \c MBEDTLS_AES_ENCRYPT_ALT. * - * \param ctx AES context - * \param input Plaintext block - * \param output Output (ciphertext) block + * \param ctx The AES context to use for encryption. + * \param input The plaintext 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, const unsigned char input[16], unsigned char output[16] ); /** - * \brief Internal AES block decryption function - * (Only exposed to allow overriding it, - * see MBEDTLS_AES_DECRYPT_ALT) + * \brief Internal AES block decryption function. This is only + * exposed to allow overriding it using see + * \c MBEDTLS_AES_DECRYPT_ALT. * - * \param ctx AES context - * \param input Ciphertext block - * \param output Output (plaintext) block + * \param ctx The AES context to use for decryption. + * \param input The ciphertext 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, 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 * 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 input Plaintext block - * \param output Output (ciphertext) block + * \param ctx The AES context to use for encryption. + * \param input Plaintext block. + * \param output Output (ciphertext) block. */ MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx, 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 * 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 input Ciphertext block - * \param output Output (plaintext) block + * \param ctx The AES context to use for decryption. + * \param input Ciphertext block. + * \param output Output (plaintext) block. */ MBEDTLS_DEPRECATED void mbedtls_aes_decrypt( mbedtls_aes_context *ctx, const unsigned char input[16], @@ -336,9 +404,9 @@ extern "C" { #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 ); diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h index 1459eb8eab..5a9ee4a1cd 100644 --- a/include/mbedtls/ccm.h +++ b/include/mbedtls/ccm.h @@ -1,10 +1,19 @@ /** * \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: + * + * */ /* - * 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 * * 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 * 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 #define MBEDTLS_CCM_H #include "cipher.h" -#define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D /**< Bad input parameters to function. */ -#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_BAD_INPUT -0x000D /**< Bad input parameters to the function. */ +#define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F /**< Authenticated decryption failed. */ +#define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */ #if !defined(MBEDTLS_CCM_ALT) // Regular implementation @@ -39,31 +49,33 @@ extern "C" { #endif /** - * \brief CCM context structure + * \brief The CCM context-type definition. The CCM context is passed + * to the APIs called. */ typedef struct { - mbedtls_cipher_context_t cipher_ctx; /*!< cipher context used */ + mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */ } mbedtls_ccm_context; /** - * \brief Initialize CCM context (just makes references valid) - * Makes the context ready for mbedtls_ccm_setkey() or - * mbedtls_ccm_free(). + * \brief This function initializes the specified CCM context, + * to make references valid, and prepare the context + * 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 ); /** - * \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 cipher cipher to use (a 128-bit block cipher) - * \param key encryption key - * \param keybits key size in bits (must be acceptable by the cipher) + * \param ctx The CCM context to initialize. + * \param cipher The 128-bit block cipher to use. + * \param key The encryption key. + * \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, mbedtls_cipher_id_t cipher, @@ -71,36 +83,37 @@ int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx, 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 ); /** - * \brief CCM buffer encryption + * \brief This function encrypts a buffer using CCM. * - * \param ctx CCM context - * \param length length of the input data in bytes - * \param iv nonce (initialization vector) - * \param iv_len length of IV in bytes - * must be 2, 3, 4, 5, 6, 7 or 8 - * \param add additional data - * \param add_len length of additional data in bytes - * must be less than 2^16 - 2^8 - * \param input buffer holding the input data - * \param output buffer for holding the output data - * must be at least 'length' bytes wide - * \param tag buffer for holding the tag - * \param tag_len length of the tag to generate in bytes - * must be 4, 6, 8, 10, 14 or 16 + * \param ctx The CCM context to use for encryption. + * \param length The length of the input data in Bytes. + * \param iv Initialization vector (nonce). + * \param iv_len The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13. + * \param add The additional data field. + * \param add_len The length of additional data in Bytes. + * Must be less than 2^16 - 2^8. + * \param input The buffer holding the input data. + * \param output The buffer holding the output data. + * Must be at least \p length Bytes wide. + * \param tag The buffer holding the tag. + * \param tag_len The length of the tag to generate in Bytes: + * 4, 6, 8, 10, 14 or 16. * - * \note The tag is written to a separate buffer. To get the tag - * concatenated with the output as in the CCM spec, use - * tag = output + length and make sure the output buffer is - * at least length + tag_len wide. + * \note The tag is written to a separate buffer. To concatenate + * the \p tag with the \p output, as done in RFC-3610: + * Counter with CBC-MAC (CCM), use + * \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, 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 ); /** - * \brief CCM buffer authenticated decryption + * \brief This function performs a CCM authenticated decryption of a + * buffer. * - * \param ctx CCM context - * \param length length of the input data - * \param iv initialization vector - * \param iv_len length of IV - * \param add additional data - * \param add_len length of additional data - * \param input buffer holding the input data - * \param output buffer for holding the output data - * \param tag buffer holding the tag - * \param tag_len length of the tag + * \param ctx The CCM context to use for decryption. + * \param length The length of the input data in Bytes. + * \param iv Initialization vector. + * \param iv_len The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13. + * \param add The additional data field. + * \param add_len The length of additional data in Bytes. + * \param input The buffer holding the input data. + * \param output The buffer holding the output data. + * \param tag The buffer holding the tag. + * \param tag_len The length of the tag in Bytes. * - * \return 0 if successful and authenticated, - * MBEDTLS_ERR_CCM_AUTH_FAILED if tag does not match + * \return 0 if successful and authenticated, or + * #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. */ int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, 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 -#else /* !MBEDTLS_CCM_ALT */ +#else /* MBEDTLS_CCM_ALT */ #include "ccm_alt.h" -#endif /* !MBEDTLS_CCM_ALT */ +#endif /* MBEDTLS_CCM_ALT */ #ifdef __cplusplus extern "C" { @@ -145,9 +159,9 @@ extern "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 ); #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */ diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h index 97b9226f5c..dc1bc56470 100644 --- a/include/mbedtls/cipher.h +++ b/include/mbedtls/cipher.h @@ -1,12 +1,12 @@ /** * \file cipher.h * - * \brief Generic cipher wrapper. + * \brief The generic cipher wrapper. * * \author Adriaan de Jong */ /* - * 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 * * 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 * 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 @@ -52,22 +52,23 @@ #define inline __inline #endif -#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_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_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_INVALID_CONTEXT -0x6380 /**< The context is invalid, eg because it was free()ed. */ -#define MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED -0x6400 /**< Cipher hardware accelerator failed. */ +#define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080 /**< The selected feature is not available. */ +#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_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_AUTH_FAILED -0x6300 /**< Authentication failed (for AEAD modes). */ +#define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380 /**< The context is invalid. For example, because it was freed. */ +#define MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED -0x6400 /**< Cipher hardware accelerator failed. */ -#define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01 /**< Cipher accepts IVs of variable length */ -#define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02 /**< Cipher accepts keys 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. */ #ifdef __cplusplus extern "C" { #endif +/** Supported cipher IDs. */ typedef enum { MBEDTLS_CIPHER_ID_NONE = 0, MBEDTLS_CIPHER_ID_NULL, @@ -79,6 +80,7 @@ typedef enum { MBEDTLS_CIPHER_ID_ARC4, } mbedtls_cipher_id_t; +/** Supported cipher types. */ typedef enum { MBEDTLS_CIPHER_NONE = 0, MBEDTLS_CIPHER_NULL, @@ -131,6 +133,7 @@ typedef enum { MBEDTLS_CIPHER_CAMELLIA_256_CCM, } mbedtls_cipher_type_t; +/** Supported cipher modes. */ typedef enum { MBEDTLS_MODE_NONE = 0, MBEDTLS_MODE_ECB, @@ -143,14 +146,16 @@ typedef enum { MBEDTLS_MODE_CCM, } mbedtls_cipher_mode_t; +/** Supported cipher padding types. */ typedef enum { - MBEDTLS_PADDING_PKCS7 = 0, /**< PKCS7 padding (default) */ - MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding */ - MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding */ - MBEDTLS_PADDING_ZEROS, /**< zero padding (not reversible!) */ - MBEDTLS_PADDING_NONE, /**< never pad (full blocks only) */ + MBEDTLS_PADDING_PKCS7 = 0, /**< PKCS7 padding (default). */ + MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding. */ + MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding. */ + MBEDTLS_PADDING_ZEROS, /**< zero padding (not reversible). */ + MBEDTLS_PADDING_NONE, /**< never pad (full blocks only). */ } mbedtls_cipher_padding_t; +/** Type of operation. */ typedef enum { MBEDTLS_OPERATION_NONE = -1, MBEDTLS_DECRYPT = 0, @@ -158,19 +163,19 @@ typedef enum { } mbedtls_operation_t; enum { - /** Undefined key length */ + /** Undefined key length. */ 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, - /** 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, - /** 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, }; -/** Maximum length of any IV, in bytes */ +/** Maximum length of any IV, in Bytes. */ #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 /** @@ -184,33 +189,40 @@ typedef struct mbedtls_cipher_base_t mbedtls_cipher_base_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 { - /** 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; - /** Cipher mode (e.g. MBEDTLS_MODE_CBC) */ + /** The cipher mode. For example, MBEDTLS_MODE_CBC. */ mbedtls_cipher_mode_t mode; - /** Cipher key length, in bits (default length for variable sized ciphers) - * (Includes parity bits for ciphers like DES) */ + /** The cipher key length, in bits. This is the + * default length for variable sized ciphers. + * Includes parity bits for ciphers like DES. + */ unsigned int key_bitlen; - /** Name of the cipher */ + /** Name of the cipher. */ const char * name; - /** IV/NONCE size, in bytes. - * For cipher that accept many sizes: recommended size */ + /** IV or nonce size, in Bytes. + * For ciphers that accept variable IV sizes, + * this is the recommended 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; - /** block size, in bytes */ + /** The block size, in Bytes. */ unsigned int block_size; - /** Base cipher information and functions */ + /** Struct for base cipher information and functions. */ const mbedtls_cipher_base_t *base; } mbedtls_cipher_info_t; @@ -219,125 +231,133 @@ typedef struct { * Generic cipher context. */ typedef struct { - /** Information about the associated cipher */ + /** Information about the associated cipher. */ const mbedtls_cipher_info_t *cipher_info; - /** Key length to use */ + /** Key length to use. */ 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; #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 ); int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len ); #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]; - /** Number of bytes that still need processing */ + /** Number of Bytes that have not been processed yet. */ 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]; - /** IV size in bytes (for ciphers with variable-length IVs) */ + /** IV size in Bytes, for ciphers with variable-length IVs. */ size_t iv_size; - /** Cipher-specific context */ + /** The cipher-specific context. */ void *cipher_ctx; #if defined(MBEDTLS_CMAC_C) - /** CMAC Specific context */ + /** CMAC-specific context. */ mbedtls_cmac_context_t *cmac_ctx; #endif } 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 - * is 0. + * \return A statically-allocated array of ciphers. The last entry + * is zero. */ const int *mbedtls_cipher_list( void ); /** - * \brief Returns the cipher information structure associated - * with the given cipher name. + * \brief This function retrieves the cipher-information + * structure associated with the given cipher name. * * \param cipher_name Name of the cipher to search for. * - * \return the cipher information structure associated with the - * given cipher_name, or NULL if not found. + * \return The cipher information structure associated with the + * given \p cipher_name, or NULL if not found. */ const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name ); /** - * \brief Returns the cipher information structure associated - * with the given cipher type. + * \brief This function retrieves the cipher-information + * structure associated with the given cipher type. * * \param cipher_type Type of the cipher to search for. * - * \return the cipher information structure associated with the - * given cipher_type, or NULL if not found. + * \return The cipher information structure associated with the + * 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 ); /** - * \brief Returns the cipher information structure associated - * with the given cipher id, key size and mode. + * \brief This function retrieves the cipher-information + * structure associated with the given cipher ID, + * key size and mode. * - * \param cipher_id Id of the cipher to search for - * (e.g. MBEDTLS_CIPHER_ID_AES) - * \param key_bitlen Length of the key in bits - * \param mode Cipher mode (e.g. MBEDTLS_MODE_CBC) + * \param cipher_id The ID of the cipher to search for. For example, + * #MBEDTLS_CIPHER_ID_AES. + * \param key_bitlen The length of the key in bits. + * \param mode The cipher mode. For example, #MBEDTLS_MODE_CBC. * - * \return the cipher information structure associated with the - * given cipher_type, or NULL if not found. + * \return The cipher information structure associated with the + * 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, int key_bitlen, 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 ); /** - * \brief Free and clear the cipher-specific context of ctx. - * Freeing ctx itself remains the responsibility of the - * caller. + * \brief This function frees and clears the cipher-specific + * context of \p ctx. Freeing \p ctx itself remains the + * responsibility of the caller. */ void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx ); + /** - * \brief Initialises and fills the cipher context structure with - * the appropriate values. + * \brief This function initializes and fills the cipher-context + * structure with the appropriate values. It also clears + * the structure. * - * \note Currently also clears structure. In future versions you - * will be required to call mbedtls_cipher_init() on the structure - * first. + * \param ctx The context to initialize. May not be NULL. + * \param cipher_info The cipher to use. * - * \param ctx context to initialise. May not be NULL. - * \param cipher_info cipher to use. - * - * \return 0 on success, - * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure, - * MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the + * \return \c 0 on success, + * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure, + * #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the * 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 ); /** - * \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 - * initialised. + * \return The size of the blocks of the cipher, or zero if \p ctx + * has not been initialized. */ 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. - * (e.g. MBEDTLS_MODE_CBC) + * \brief This function returns the mode of operation for + * 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 - * has not been initialised. + * \return The mode of operation, or #MBEDTLS_MODE_NONE if + * \p ctx has not been initialized. */ static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtls_cipher_context_t *ctx ) { @@ -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 - * (0 for ciphers not using IV/NONCE). - * If IV has already been set: actual size. + * \return */ 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 - * not been initialised. + * \return The type of the cipher, or #MBEDTLS_CIPHER_NONE if + * \p ctx has not been initialized. */ static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( const mbedtls_cipher_context_t *ctx ) { @@ -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 ) { @@ -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 - * MBEDTLS_KEY_LENGTH_NONE if ctx has not been - * initialised. + * \return The key length of the cipher in bits, or + * #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been + * initialized. */ static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t *ctx ) { @@ -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), - * or MBEDTLS_OPERATION_NONE if ctx has not been - * initialised. + * \return The type of operation: #MBEDTLS_ENCRYPT or + * #MBEDTLS_DECRYPT, or #MBEDTLS_OPERATION_NONE if \p ctx + * has not been initialized. */ static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_cipher_context_t *ctx ) { @@ -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 - * initialised using cipher_context_from_type or - * cipher_context_from_string. + * \param ctx The generic cipher context. May not be NULL. Must have + * been initialized using mbedtls_cipher_info_from_type() + * or mbedtls_cipher_info_from_string(). * \param key The key to use. - * \param key_bitlen key length to use, in bits. - * \param operation Operation that the key will be used for, either - * MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT. + * \param key_bitlen The key length to use, in bits. + * \param operation The operation that the key will be used for: + * #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT. * - * \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if - * parameter verification fails or a cipher specific + * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if + * parameter verification fails, or a cipher-specific * error code. */ 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) /** - * \brief Set padding mode, for cipher modes that use padding. - * (Default: PKCS7 padding.) + * \brief This function sets the padding mode, for cipher modes + * that use padding. * - * \param ctx generic cipher context - * \param mode padding mode + * The default passing mode is PKCS7 padding. * - * \returns 0 on success, MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE - * if selected padding mode is not supported, or - * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode + * \param ctx The generic cipher context. + * \param mode The padding mode. + * + * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE + * if the selected padding mode is not supported, or + * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode * does not support padding. */ int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_cipher_padding_t mode ); #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 iv IV to use (or NONCE_COUNTER for CTR-mode ciphers) - * \param iv_len IV length for ciphers with variable-size IV; - * discarded by ciphers with fixed-size IV. + * \param ctx The generic cipher context. + * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. + * \param iv_len The IV length for ciphers with variable-size IV. + * This parameter is discarded by ciphers with fixed-size IV. * - * \returns 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 - * ciphers, this function has no effect. + * \note Some ciphers do not use IVs nor nonce. For these + * ciphers, this function has no effect. */ int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx, 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 - * if parameter verification fails. + * \returns \c 0 on success, #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA + * if parameter verification fails. */ int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx ); #if defined(MBEDTLS_GCM_C) /** - * \brief Add additional data (for AEAD ciphers). - * Currently only supported with GCM. - * Must be called exactly once, after mbedtls_cipher_reset(). + * \brief This function adds additional data for AEAD ciphers. + * Only supported with GCM. Must be called + * exactly once, after mbedtls_cipher_reset(). * - * \param ctx generic cipher context - * \param ad Additional data to use. - * \param ad_len Length of ad. + * \param ctx The generic cipher context. + * \param ad The additional data to use. + * \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, const unsigned char *ad, size_t ad_len ); #endif /* MBEDTLS_GCM_C */ /** - * \brief Generic cipher update function. Encrypts/decrypts - * using the given cipher context. Writes as many block - * size'd blocks of data as possible to output. Any data - * that cannot be written immediately will either be added - * to the next block, or flushed when cipher_final is - * called. - * Exception: for MBEDTLS_MODE_ECB, expects single block - * in size (e.g. 16 bytes for AES) + * \brief The generic cipher update function. It encrypts or + * decrypts using the given cipher context. Writes as + * many block-sized blocks of data as possible to output. + * Any data that cannot be written immediately is either + * added to the next block, or flushed when + * mbedtls_cipher_finish() is called. + * Exception: For MBEDTLS_MODE_ECB, expects a single block + * in size. For example, 16 Bytes for AES. * - * \param ctx generic cipher context - * \param input buffer holding the input data - * \param ilen length of the input data - * \param output buffer for the output data. Should be able to hold at - * least ilen + block_size. Cannot be the same buffer as - * input! - * \param olen length of the output data, will be filled with the - * actual number of bytes written. + * \param ctx The generic cipher context. + * \param input The buffer holding the input data. + * \param ilen The length of the input data. + * \param output The buffer for the output data. Must be able to hold at + * least \p ilen + block_size. Must not be the same buffer + * as input. + * \param olen The length of the output data, to be updated with the + * 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, - * MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an - * unsupported mode for a cipher or a cipher specific + * #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an + * unsupported mode for a cipher, or a cipher-specific * error code. * * \note If the underlying cipher is GCM, all calls to this - * function, except the last one before mbedtls_cipher_finish(), - * must have ilen a multiple of the block size. + * function, except the last one before + * mbedtls_cipher_finish(). Must have \p ilen as a + * multiple of the block_size. */ int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen ); /** - * \brief Generic cipher finalisation function. If data still - * needs to be flushed from an incomplete block, data - * contained within it will be padded with the size of - * the last block, and written to the output buffer. + * \brief The generic cipher finalization function. If data still + * needs to be flushed from an incomplete block, the data + * contained in it is padded to the size of + * the last block, and written to the \p output buffer. * - * \param ctx Generic cipher context - * \param output buffer to write data to. Needs block_size available. - * \param olen length of the data written to the output buffer. + * \param ctx The generic cipher context. + * \param output The buffer to write data to. Needs block_size available. + * \param olen The length of the data written to the \p output buffer. * - * \returns 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, - * 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, - * MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding - * while decrypting or a cipher specific error code. + * #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding + * while decrypting, or a cipher-specific error code + * on failure for any other reason. */ int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx, unsigned char *output, size_t *olen ); #if defined(MBEDTLS_GCM_C) /** - * \brief Write tag for AEAD ciphers. - * Currently only supported with GCM. + * \brief This function writes a tag for AEAD ciphers. + * Only supported with GCM. * Must be called after mbedtls_cipher_finish(). * - * \param ctx Generic cipher context - * \param tag buffer to write the tag - * \param tag_len Length of the tag to write + * \param ctx The generic cipher context. + * \param tag The buffer to write the tag to. + * \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, unsigned char *tag, size_t tag_len ); /** - * \brief Check tag for AEAD ciphers. - * Currently only supported with GCM. + * \brief This function checks the tag for AEAD ciphers. + * Only supported with GCM. * Must be called after mbedtls_cipher_finish(). * - * \param ctx Generic cipher context - * \param tag Buffer holding the tag - * \param tag_len Length of the tag to check + * \param ctx The generic cipher context. + * \param tag The buffer holding the tag. + * \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, const unsigned char *tag, size_t tag_len ); #endif /* MBEDTLS_GCM_C */ /** - * \brief Generic all-in-one encryption/decryption - * (for all ciphers except AEAD constructs). + * \brief The generic all-in-one encryption/decryption function, + * for all ciphers except AEAD constructs. * - * \param ctx generic cipher context - * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers) - * \param iv_len IV length for ciphers with variable-size IV; - * discarded by ciphers with fixed-size IV. - * \param input buffer holding the input data - * \param ilen length of the input data - * \param output buffer for the output data. Should be able to hold at - * least ilen + block_size. Cannot be the same buffer as - * input! - * \param olen length of the output data, will be filled with the - * actual number of bytes written. + * \param ctx The generic cipher context. + * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. + * \param iv_len The IV length for ciphers with variable-size IV. + * This parameter is discarded by ciphers with fixed-size + * IV. + * \param input The buffer holding the input data. + * \param ilen The length of the input data. + * \param output The buffer for the output data. Must be able to hold at + * least \p ilen + block_size. Must not be the same buffer + * as input. + * \param olen The length of the output data, to be updated with the + * actual number of Bytes written. * - * \note Some ciphers don't use IVs nor NONCE. For these - * ciphers, use iv = NULL and iv_len = 0. + * \note Some ciphers do not use IVs nor nonce. For these + * ciphers, use \p iv = NULL and \p iv_len = 0. * - * \returns 0 on success, or - * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or - * MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption + * \returns \c 0 on success, or + * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or + * #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption * expected a full block but was not provided one, or - * MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding - * while decrypting, or - * a cipher specific error code. + * #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding + * while decrypting, or a cipher-specific error code on + * failure for any other reason. */ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, @@ -641,26 +670,26 @@ int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx, #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 iv IV to use (or NONCE_COUNTER for CTR-mode ciphers) - * \param iv_len IV length for ciphers with variable-size IV; - * discarded by ciphers with fixed-size IV. - * \param ad Additional data to authenticate. - * \param ad_len Length of ad. - * \param input buffer holding the input data - * \param ilen length of the input data - * \param output buffer for the output data. - * Should be able to hold at least ilen. - * \param olen length of the output data, will be filled with the - * actual number of bytes written. - * \param tag buffer for the authentication tag - * \param tag_len desired tag length + * \param ctx The generic cipher context. + * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. + * \param iv_len The IV length for ciphers with variable-size IV. + * This parameter is discarded by ciphers with fixed-size IV. + * \param ad The additional data to authenticate. + * \param ad_len The length of \p ad. + * \param input The buffer holding the input data. + * \param ilen The length of the input data. + * \param output The buffer for the output data. + * Must be able to hold at least \p ilen. + * \param olen The length of the output data, to be updated with the + * actual number of Bytes written. + * \param tag The buffer for the authentication tag. + * \param tag_len The desired length of the authentication tag. * - * \returns 0 on success, or - * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or - * a cipher specific error code. + * \returns \c 0 on success, or + * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or + * a cipher-specific error code. */ int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx, 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 ); /** - * \brief Generic autenticated decryption (AEAD ciphers). + * \brief The generic autenticated decryption (AEAD) function. * - * \param ctx generic cipher context - * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers) - * \param iv_len IV length for ciphers with variable-size IV; - * discarded by ciphers with fixed-size IV. - * \param ad Additional data to be authenticated. - * \param ad_len Length of ad. - * \param input buffer holding the input data - * \param ilen length of the input data - * \param output buffer for the output data. - * Should be able to hold at least ilen. - * \param olen length of the output data, will be filled with the - * actual number of bytes written. - * \param tag buffer holding the authentication tag - * \param tag_len length of the authentication tag + * \param ctx The generic cipher context. + * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. + * \param iv_len The IV length for ciphers with variable-size IV. + * This parameter is discarded by ciphers with fixed-size IV. + * \param ad The additional data to be authenticated. + * \param ad_len The length of \p ad. + * \param input The buffer holding the input data. + * \param ilen The length of the input data. + * \param output The buffer for the output data. + * Must be able to hold at least \p ilen. + * \param olen The length of the output data, to be updated with the + * actual number of Bytes written. + * \param tag The buffer holding the authentication tag. + * \param tag_len The length of the authentication tag. * - * \returns 0 on success, or - * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or - * MBEDTLS_ERR_CIPHER_AUTH_FAILED if data isn't authentic, - * or a cipher specific error code. + * \returns \c 0 on success, or + * #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or + * #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic, + * or a cipher-specific error code on failure for any other reason. * * \note If the data is not authentic, then the output buffer - * is zeroed out to prevent the unauthentic plaintext to - * be used by mistake, making this interface safer. + * is zeroed out to prevent the unauthentic plaintext being + * used, making this interface safer. */ int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, diff --git a/include/mbedtls/cmac.h b/include/mbedtls/cmac.h index 1cac948968..628c9daba2 100644 --- a/include/mbedtls/cmac.h +++ b/include/mbedtls/cmac.h @@ -1,11 +1,11 @@ /** * \file cmac.h * - * \brief Cipher-based Message Authentication Code (CMAC) Mode for - * Authentication + * \brief The Cipher-based Message Authentication Code (CMAC) Mode for + * 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 * * 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 * 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 #define MBEDTLS_CMAC_H @@ -31,110 +32,125 @@ extern "C" { #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_DES3_BLOCK_SIZE 8 #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 -#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 #if !defined(MBEDTLS_CMAC_ALT) /** - * CMAC context structure - Contains internal state information only + * The CMAC context structure. */ 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]; /** 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]; - /** Length of data pending to be processed */ + /** The length of data pending processing. */ size_t unprocessed_len; }; /** - * \brief Set the CMAC key and prepare to authenticate the input - * data. - * Should be called with an initialized cipher context. + * \brief This function sets the CMAC key, and prepares to authenticate + * the input data. + * Must be called with an initialized cipher context. * - * \param ctx Cipher context. This should be a cipher context, - * initialized to be one of the following types: - * MBEDTLS_CIPHER_AES_128_ECB, MBEDTLS_CIPHER_AES_192_ECB, - * MBEDTLS_CIPHER_AES_256_ECB or - * MBEDTLS_CIPHER_DES_EDE3_ECB. - * \param key CMAC key - * \param keybits length of the CMAC key in bits - * (must be acceptable by the cipher) + * \param ctx The cipher context used for the CMAC operation, initialized + * as one of the following types: + * \param key The CMAC key. + * \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, const unsigned char *key, size_t keybits ); /** - * \brief Generic CMAC process buffer. - * Called between mbedtls_cipher_cmac_starts() or - * mbedtls_cipher_cmac_reset() and - * mbedtls_cipher_cmac_finish(). - * May be called repeatedly. + * \brief This function feeds an input buffer into an ongoing CMAC + * computation. * - * \param ctx CMAC context - * \param input buffer holding the data - * \param ilen length of the input data + * It is called between mbedtls_cipher_cmac_starts() or + * mbedtls_cipher_cmac_reset(), and mbedtls_cipher_cmac_finish(). + * Can be called repeatedly. * - * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter - * verification fails. + * \param ctx The cipher context used for the CMAC operation. + * \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, const unsigned char *input, size_t ilen ); /** - * \brief Output CMAC. - * Called after mbedtls_cipher_cmac_update(). - * Usually followed by mbedtls_cipher_cmac_reset(), then - * mbedtls_cipher_cmac_starts(), or mbedtls_cipher_free(). + * \brief This function finishes the CMAC operation, and writes + * the result to the output buffer. * - * \param ctx CMAC context - * \param output Generic CMAC checksum result + * It is called after mbedtls_cipher_cmac_update(). + * It can be followed by mbedtls_cipher_cmac_reset() and + * mbedtls_cipher_cmac_update(), or mbedtls_cipher_free(). * - * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter - * verification fails. + * \param ctx The cipher context used for the CMAC operation. + * \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, unsigned char *output ); /** - * \brief Prepare to authenticate a new message with the same key. - * Called after mbedtls_cipher_cmac_finish() and before - * mbedtls_cipher_cmac_update(). + * \brief This function prepares the authentication of another + * message with the same key as the previous CMAC + * 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 - * verification fails. + * \param ctx The cipher context used for the CMAC operation. + * + * \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 ); /** - * \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 - * \param key CMAC key - * \param keylen length of the CMAC key in bits - * \param input buffer holding the data - * \param ilen length of the input data - * \param output Generic CMAC-result + * The function allocates the context, performs the + * calculation, and frees the context. * - * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter - * verification fails. + * The CMAC result is calculated as + * 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, 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) /** - * \brief AES-CMAC-128-PRF - * Implementation of (AES-CMAC-PRF-128), as defined in RFC 4615 + * \brief This function implements the AES-CMAC-PRF-128 pseudorandom + * function, as defined in + * 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). * - * \param key PRF key - * \param key_len PRF key length in bytes - * \param input buffer holding the input data - * \param in_len length of the input data in bytes - * \param output buffer holding the generated pseudorandom output (16 bytes) + * \param key The key to use. + * \param key_len The key length in Bytes. + * \param input The buffer holding the input data. + * \param in_len The length of the input data in Bytes. + * \param output The buffer holding the generated 16 Bytes of + * pseudorandom output. * - * \return 0 if successful + * \return \c 0 on success. */ int mbedtls_aes_cmac_prf_128( const unsigned char *key, size_t key_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) ) /** - * \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 ); #endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */ diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h index 01cd826a17..121575a51b 100644 --- a/include/mbedtls/ctr_drbg.h +++ b/include/mbedtls/ctr_drbg.h @@ -1,10 +1,13 @@ /** * \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 NIST SP 800-90A: + * Recommendation for Random Number Generation Using Deterministic + * Random Bit Generators. + * */ /* - * 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 * * 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 * 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 #define MBEDTLS_CTR_DRBG_H @@ -31,78 +35,95 @@ #endif #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_INPUT_TOO_BIG -0x0038 /**< Input too large (Entropy + additional). */ -#define MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR -0x003A /**< Read/write error in file. */ +#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 /**< The input (entropy + additional data) is too large. */ +#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_KEYSIZE 32 /**< Key size used by the cipher */ -#define MBEDTLS_CTR_DRBG_KEYBITS ( MBEDTLS_CTR_DRBG_KEYSIZE * 8 ) -#define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) - /**< The seed length (counter + AES key) */ +#define MBEDTLS_CTR_DRBG_BLOCKSIZE 16 /**< The block 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 ) /**< The key size for the DRBG operation, in bits. */ +#define MBEDTLS_CTR_DRBG_SEEDLEN ( MBEDTLS_CTR_DRBG_KEYSIZE + MBEDTLS_CTR_DRBG_BLOCKSIZE ) /**< The seed length, calculated as (counter + AES key). */ /** * \name SECTION: Module settings * * 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_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: + * + */ #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: + * + */ #endif #endif #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 #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 #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 #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 /* \} name SECTION: Module settings */ -#define MBEDTLS_CTR_DRBG_PR_OFF 0 /**< No prediction resistance */ -#define MBEDTLS_CTR_DRBG_PR_ON 1 /**< Prediction resistance enabled */ +#define MBEDTLS_CTR_DRBG_PR_OFF 0 +/**< Prediction resistance is disabled. */ +#define MBEDTLS_CTR_DRBG_PR_ON 1 +/**< Prediction resistance is enabled. */ #ifdef __cplusplus extern "C" { #endif /** - * \brief CTR_DRBG context structure + * \brief The CTR_DRBG context structure. */ typedef struct { - unsigned char counter[16]; /*!< counter (V) */ - int reseed_counter; /*!< reseed counter */ - int prediction_resistance; /*!< enable prediction resistance (Automatic - reseed before every random generation) */ - size_t entropy_len; /*!< amount of entropy grabbed on each - (re)seed */ - int reseed_interval; /*!< reseed interval */ + unsigned char counter[16]; /*!< The counter (V). */ + int reseed_counter; /*!< The reseed counter. */ + int prediction_resistance; /*!< This determines whether prediction + resistance is enabled, that is + whether to systematically reseed before + each random generation. */ + 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) */ 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) mbedtls_threading_mutex_t mutex; @@ -111,31 +132,32 @@ typedef struct mbedtls_ctr_drbg_context; /** - * \brief CTR_DRBG context initialization - * Makes the context ready for mbedtls_ctr_drbg_seed() or - * mbedtls_ctr_drbg_free(). + * \brief This function initializes the CTR_DRBG context, + * and prepares it for mbedtls_ctr_drbg_seed() + * 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 ); /** - * \brief CTR_DRBG initial seeding - * Seed and setup entropy source for future reseeds. + * \brief This function seeds and sets up the CTR_DRBG + * entropy source for future reseeds. * - * Note: Personalization data can be provided in addition to the more generic - * entropy source to make this instantiation as unique as possible. + * \note Personalization data can be provided in addition to the more generic + * entropy source, to make this instantiation as unique as possible. * - * \param ctx CTR_DRBG context to be seeded - * \param f_entropy Entropy callback (p_entropy, buffer to fill, buffer - * length) - * \param p_entropy Entropy context - * \param custom Personalization data (Device specific identifiers) - * (Can be NULL) - * \param len Length of personalization data + * \param ctx The CTR_DRBG context to seed. + * \param f_entropy The entropy callback, taking as arguments the + * \p p_entropy context, the buffer to fill, and the + length of the buffer. + * \param p_entropy The entropy context. + * \param custom Personalization data, that is device-specific + identifiers. Can be NULL. + * \param len The length of the personalization data. * - * \return 0 if successful, or - * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED + * \return \c 0 on success, or + * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure. */ int mbedtls_ctr_drbg_seed( mbedtls_ctr_drbg_context *ctx, 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 ); /** - * \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 ); /** - * \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! - * Only use this if you have ample supply of good entropy! + * \note If enabled, entropy is gathered at the beginning of + * 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 resistance MBEDTLS_CTR_DRBG_PR_ON or MBEDTLS_CTR_DRBG_PR_OFF + * \param ctx The CTR_DRBG context. + * \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, int resistance ); /** - * \brief Set the amount of entropy grabbed on each (re)seed - * (Default: MBEDTLS_CTR_DRBG_ENTROPY_LEN) + * \brief This function sets the amount of entropy grabbed on each + * seed or reseed. The default value is + * #MBEDTLS_CTR_DRBG_ENTROPY_LEN. * - * \param ctx CTR_DRBG context - * \param len Amount of entropy to grab + * \param ctx The CTR_DRBG context. + * \param len The amount of entropy to grab. */ void mbedtls_ctr_drbg_set_entropy_len( mbedtls_ctr_drbg_context *ctx, size_t len ); /** - * \brief Set the reseed interval - * (Default: MBEDTLS_CTR_DRBG_RESEED_INTERVAL) + * \brief This function sets the reseed interval. + * The default value is #MBEDTLS_CTR_DRBG_RESEED_INTERVAL. * - * \param ctx CTR_DRBG context - * \param interval Reseed interval + * \param ctx The CTR_DRBG context. + * \param interval The reseed interval. */ void mbedtls_ctr_drbg_set_reseed_interval( mbedtls_ctr_drbg_context *ctx, 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 additional Additional data to add to state (Can be NULL) - * \param len Length of additional data + * \param ctx The CTR_DRBG context. + * \param additional Additional data to add to the state. Can be NULL. + * \param len The length of the additional data. * - * \return 0 if successful, or - * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED + * \return \c 0 on success, or + * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on failure. */ int mbedtls_ctr_drbg_reseed( mbedtls_ctr_drbg_context *ctx, 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 additional Additional data to update state with - * \param add_len Length of additional data + * \param ctx The CTR_DRBG context. + * \param additional The data to update the state with. + * \param add_len Length of \p additional data. * - * \note If add_len is greater than MBEDTLS_CTR_DRBG_MAX_SEED_INPUT, - * only the first MBEDTLS_CTR_DRBG_MAX_SEED_INPUT bytes are used, - * the remaining ones are silently discarded. + * \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. + * The remaining Bytes are silently discarded. */ void mbedtls_ctr_drbg_update( mbedtls_ctr_drbg_context *ctx, 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 output Buffer to fill - * \param output_len Length of the buffer - * \param additional Additional data to update with (Can be NULL) - * \param add_len Length of additional data + * \param p_rng The CTR_DRBG context. This must be a pointer to a + * #mbedtls_ctr_drbg_context structure. + * \param output The buffer to fill. + * \param output_len The length of the buffer. + * \param additional Additional data to update. Can be NULL. + * \param add_len The length of the additional data. * - * \return 0 if successful, or - * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or - * MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG + * \return \c 0 on success, or + * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or + * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure. */ int mbedtls_ctr_drbg_random_with_add( void *p_rng, unsigned char *output, size_t output_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 output Buffer to fill - * \param output_len Length of the buffer + * \param p_rng The CTR_DRBG context. This must be a pointer to a + * #mbedtls_ctr_drbg_context structure. + * \param output The buffer to fill. + * \param output_len The length of the buffer. * - * \return 0 if successful, or - * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED, or - * MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG + * \return \c 0 on success, or + * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or + * #MBEDTLS_ERR_CTR_DRBG_REQUEST_TOO_BIG on failure. */ int mbedtls_ctr_drbg_random( void *p_rng, unsigned char *output, size_t output_len ); #if defined(MBEDTLS_FS_IO) /** - * \brief Write a seed file + * \brief This function writes a seed file. * - * \param ctx CTR_DRBG context - * \param path Name of the file + * \param ctx The CTR_DRBG context. + * \param path The name of the file. * - * \return 0 if successful, - * MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or - * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED + * \return \c 0 on success, + * #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, or + * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED on + * failure. */ 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 - * instance + * \brief This function reads and updates a seed file. The seed + * is added to this instance. * - * \param ctx CTR_DRBG context - * \param path Name of the file + * \param ctx The CTR_DRBG context. + * \param path The name of the file. * - * \return 0 if successful, - * MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, - * MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or - * MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG + * \return \c 0 on success, + * #MBEDTLS_ERR_CTR_DRBG_FILE_IO_ERROR on file error, + * #MBEDTLS_ERR_CTR_DRBG_ENTROPY_SOURCE_FAILED or + * #MBEDTLS_ERR_CTR_DRBG_INPUT_TOO_BIG on failure. */ int mbedtls_ctr_drbg_update_seed_file( mbedtls_ctr_drbg_context *ctx, const char *path ); #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 ); diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h index 8a953b9e79..da2e66b111 100644 --- a/include/mbedtls/dhm.h +++ b/include/mbedtls/dhm.h @@ -1,7 +1,15 @@ /** * \file dhm.h * - * \brief Diffie-Hellman-Merkle key exchange + * \brief Diffie-Hellman-Merkle key exchange. + * + * RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for + * Internet Key Exchange (IKE) defines a number of standardized + * Diffie-Hellman groups for IKE. + * + * RFC-5114: Additional Diffie-Hellman Groups for Use with IETF + * Standards 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 * 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 * * 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 * 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 #define MBEDTLS_DHM_H @@ -62,7 +70,7 @@ /* * 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_MAKE_PARAMS_FAILED -0x3180 /**< Making of the DHM parameters 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_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_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_SET_GROUP_FAILED -0x3580 /**< Setting the modulus and generator failed. */ @@ -79,35 +87,35 @@ extern "C" { #endif /** - * \brief DHM context structure + * \brief The DHM context structure. */ typedef struct { - size_t len; /*!< size(P) in chars */ - mbedtls_mpi P; /*!< prime modulus */ - mbedtls_mpi G; /*!< generator */ - mbedtls_mpi X; /*!< secret value */ - mbedtls_mpi GX; /*!< self = G^X mod P */ - mbedtls_mpi GY; /*!< peer = G^Y mod P */ - mbedtls_mpi K; /*!< key = GY^X mod P */ - mbedtls_mpi RP; /*!< cached R^2 mod P */ - mbedtls_mpi Vi; /*!< blinding value */ - mbedtls_mpi Vf; /*!< un-blinding value */ - mbedtls_mpi pX; /*!< previous X */ + size_t len; /*!< The size of \p P in Bytes. */ + mbedtls_mpi P; /*!< The prime modulus. */ + mbedtls_mpi G; /*!< The generator. */ + mbedtls_mpi X; /*!< Our secret value. */ + mbedtls_mpi GX; /*!< Our public key = \c G^X mod \c P. */ + mbedtls_mpi GY; /*!< The public key of the peer = \c G^Y mod \c P. */ + mbedtls_mpi K; /*!< The shared secret = \c G^(XY) mod \c P. */ + mbedtls_mpi RP; /*!< The cached value = \c R^2 mod \c P. */ + mbedtls_mpi Vi; /*!< The blinding value. */ + mbedtls_mpi Vf; /*!< The unblinding value. */ + mbedtls_mpi pX; /*!< The previous \c X. */ } 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 ); /** - * \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. * On output, *p is updated to point to the end of the data * 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 * detected, which is usually not useful except to debug * 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, unsigned char **p, 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 x_size private value size in bytes - * \param output destination buffer - * \param olen number of chars written - * \param f_rng RNG function - * \param p_rng RNG parameter + * \param ctx The DHM context. + * \param x_size The private value size in Bytes. + * \param olen The number of characters written. + * \param output The destination buffer. + * \param f_rng The RNG function. + * \param p_rng The RNG parameter. * * \note The destination buffer must be large enough to hold * 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 * 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 - * \c mbedtls_dhm_set_group below in conjunction with - * \c mbedtls_mpi_read_binary and \c mbedtls_mpi_read_string. + * mbedtls_dhm_set_group() below in conjunction with + * 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, 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 * - * \param ctx DHM context - * \param P MPI holding DHM prime modulus - * \param G MPI holding DHM generator + * \param ctx The DHM context. + * \param P The MPI holding DHM prime modulus. + * \param G The MPI holding DHM generator. * * \note This function can be used to set P, G * 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, const mbedtls_mpi *P, 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 input input buffer - * \param ilen size of buffer + * \param ctx The DHM context. + * \param input The input 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, 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 x_size private value size in bytes - * \param output destination buffer - * \param olen size of the destination buffer; - * must be at least equal to the size of P, ctx->len - * \param f_rng RNG function - * \param p_rng RNG parameter + * \param ctx The DHM context. + * \param x_size The private value size in Bytes. + * \param output The destination buffer. + * \param olen The length of the destination buffer. Must be at least + equal to ctx->len (the size of \c P). + * \param f_rng The RNG function. + * \param p_rng The RNG parameter. * * \note The destination buffer will always be fully written * so as to contain a big-endian presentation of G^X mod P. * If it is larger than ctx->len, it will accordingly be * 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, 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 ); /** - * \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 output destination buffer - * \param output_size size of the destination buffer, must be at - * at least the size of ctx->len - * \param olen on exit, holds the actual number of bytes written - * \param f_rng RNG function, for blinding purposes - * \param p_rng RNG parameter + * \param ctx The DHM context. + * \param output The destination buffer. + * \param output_size The size of the destination buffer. Must be at least + * the size of ctx->len. + * \param olen On exit, holds the actual number of Bytes written. + * \param f_rng The RNG function, for blinding purposes. + * \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 - * countermeasure against timing attacks. Blinding is - * automatically used if and only if our secret value X is - * re-used and costs nothing otherwise, so it is recommended - * to always pass a non-NULL f_rng argument. + * \note If non-NULL, \p f_rng is used to blind the input as + * a countermeasure against timing attacks. Blinding is used + * only if our secret value \p X is re-used and omitted + * otherwise. Therefore, we recommend always passing a + * non-NULL \p f_rng argument. */ int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx, 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 ); /** - * \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 ); #if defined(MBEDTLS_ASN1_PARSE_C) /** \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 dhmin input buffer - * \param dhminlen size of the buffer - * (including the terminating null byte for PEM data) + * \param dhm The DHM context to initialize. + * \param dhmin The input buffer. + * \param dhminlen The size of the buffer, including the terminating null + * 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, 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) /** \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 path filename to read the DHM Parameters from + * \param dhm The DHM context to load the parameters to. + * \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 ); #endif /* MBEDTLS_FS_IO */ @@ -276,9 +295,9 @@ extern "C" { #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 ); @@ -293,16 +312,16 @@ int mbedtls_dhm_self_test( int verbose ); * when configuring the Diffie-Hellman parameters by hand * through \c mbedtls_ssl_conf_dh_param. * - * Included are: - * RFC 5114 2.2. 2048-bit MODP Group with 224-bit Prime Order Subgroup - * RFC 3526 3. 2048-bit MODP Group - * RFC 3526 4. 3072-bit MODP Group - * RFC 3526 5. 4096-bit MODP Group - * RFC 7919 A.1 ffdhe2048 - * RFC 7919 A.2 ffdhe3072 - * RFC 7919 A.3 ffdhe4096 - * RFC 7919 A.4 ffdhe6144 - * RFC 7919 A.5 ffdhe8192 + * The following lists the source of the above groups in the standards: + * - RFC 5114 section 2.2: 2048-bit MODP Group with 224-bit Prime Order Subgroup + * - RFC 3526 section 3: 2048-bit MODP Group + * - RFC 3526 section 4: 3072-bit MODP Group + * - RFC 3526 section 5: 4096-bit MODP Group + * - RFC 7919 section A.1: ffdhe2048 + * - RFC 7919 section A.2: ffdhe3072 + * - RFC 7919 section A.3: ffdhe4096 + * - RFC 7919 section A.4: ffdhe6144 + * - RFC 7919 section A.5: ffdhe8192 * * The constants with suffix "_p" denote the chosen prime moduli, while * the constants with suffix "_g" denote the chosen generator @@ -347,6 +366,12 @@ MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t; * replacement. */ +/** + * The hexadecimal presentation of the prime underlying the + * 2048-bit MODP Group with 224-bit Prime Order Subgroup, as defined + * in RFC-5114: Additional Diffie-Hellman Groups for Use with + * IETF Standards. + */ #define MBEDTLS_DHM_RFC5114_MODP_P \ MBEDTLS_DEPRECATED_STRING_CONSTANT( \ "AD107E1E9123A9D0D660FAA79559C51FA20D64E5683B9FD1" \ @@ -361,6 +386,11 @@ MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t; "C9B53DCF4BA80A29E3FB73C16B8E75B97EF363E2FFA31F71" \ "CF9DE5384E71B81C0AC4DFFE0C10E64F" ) +/** + * The hexadecimal presentation of the chosen generator of the 2048-bit MODP + * Group with 224-bit Prime Order Subgroup, as defined in RFC-5114: + * Additional Diffie-Hellman Groups for Use with IETF Standards. + */ #define MBEDTLS_DHM_RFC5114_MODP_2048_G \ MBEDTLS_DEPRECATED_STRING_CONSTANT( \ "AC4032EF4F2D9AE39DF30B5C8FFDAC506CDEBE7B89998CAF" \ @@ -376,13 +406,16 @@ MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t; "81BC087F2A7065B384B890D3191F2BFA" ) /** + * The hexadecimal presentation of the prime underlying the 2048-bit MODP + * Group, as defined in RFC-3526: More Modular Exponential (MODP) + * Diffie-Hellman groups for Internet Key Exchange (IKE). + * * \deprecated The hex-encoded primes from RFC 3625 are deprecated and * superseded by the corresponding macros providing them as * binary constants. Their hex-encoded constants are likely * to be removed in a future version of the library. * */ - #define MBEDTLS_DHM_RFC3526_MODP_2048_P \ MBEDTLS_DEPRECATED_STRING_CONSTANT( \ "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \ @@ -397,9 +430,19 @@ MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t; "DE2BCBF6955817183995497CEA956AE515D2261898FA0510" \ "15728E5A8AACAA68FFFFFFFFFFFFFFFF" ) +/** + * The hexadecimal presentation of the chosen generator of the 2048-bit MODP + * Group, as defined in RFC-3526: More Modular Exponential (MODP) + * Diffie-Hellman groups for Internet Key Exchange (IKE). + */ #define MBEDTLS_DHM_RFC3526_MODP_2048_G \ MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" ) +/** + * The hexadecimal presentation of the prime underlying the 3072-bit MODP + * Group, as defined in RFC-3072: More Modular Exponential (MODP) + * Diffie-Hellman groups for Internet Key Exchange (IKE). + */ #define MBEDTLS_DHM_RFC3526_MODP_3072_P \ MBEDTLS_DEPRECATED_STRING_CONSTANT( \ "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \ @@ -419,9 +462,19 @@ MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t; "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31" \ "43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF" ) +/** + * The hexadecimal presentation of the chosen generator of the 3072-bit MODP + * Group, as defined in RFC-3526: More Modular Exponential (MODP) + * Diffie-Hellman groups for Internet Key Exchange (IKE). + */ #define MBEDTLS_DHM_RFC3526_MODP_3072_G \ MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" ) +/** + * The hexadecimal presentation of the prime underlying the 4096-bit MODP + * Group, as defined in RFC-3526: More Modular Exponential (MODP) + * Diffie-Hellman groups for Internet Key Exchange (IKE). + */ #define MBEDTLS_DHM_RFC3526_MODP_4096_P \ MBEDTLS_DEPRECATED_STRING_CONSTANT( \ "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1" \ @@ -447,6 +500,11 @@ MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_constant_t; "93B4EA988D8FDDC186FFB7DC90A6C08F4DF435C934063199" \ "FFFFFFFFFFFFFFFF" ) +/** + * The hexadecimal presentation of the chosen generator of the 4096-bit MODP + * Group, as defined in RFC-3526: More Modular Exponential (MODP) + * Diffie-Hellman groups for Internet Key Exchange (IKE). + */ #define MBEDTLS_DHM_RFC3526_MODP_4096_G \ MBEDTLS_DEPRECATED_STRING_CONSTANT( "02" ) diff --git a/include/mbedtls/ecdh.h b/include/mbedtls/ecdh.h index 14a362b197..99cfde00d0 100644 --- a/include/mbedtls/ecdh.h +++ b/include/mbedtls/ecdh.h @@ -1,10 +1,18 @@ /** * \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 NIST SP 800-56A Rev. 2: Recommendation for + * Pair-Wise Key Establishment Schemes Using Discrete Logarithm + * Cryptography. */ /* - * 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 * * 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 * 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 #define MBEDTLS_ECDH_H @@ -31,7 +40,9 @@ extern "C" { #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: + * */ typedef enum { @@ -40,56 +51,67 @@ typedef enum } mbedtls_ecdh_side; /** - * \brief ECDH context structure + * \brief The ECDH context structure. */ typedef struct { - mbedtls_ecp_group grp; /*!< elliptic curve used */ - mbedtls_mpi d; /*!< our secret value (private key) */ - mbedtls_ecp_point Q; /*!< our public value (public key) */ - mbedtls_ecp_point Qp; /*!< peer's public value (public key) */ - mbedtls_mpi z; /*!< shared secret */ - int point_format; /*!< format for point export in TLS messages */ - mbedtls_ecp_point Vi; /*!< blinding value (for later) */ - mbedtls_ecp_point Vf; /*!< un-blinding value (for later) */ - mbedtls_mpi _d; /*!< previous d (for later) */ + mbedtls_ecp_group grp; /*!< The elliptic curve used. */ + mbedtls_mpi d; /*!< The private key. */ + mbedtls_ecp_point Q; /*!< The public key. */ + mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */ + mbedtls_mpi z; /*!< The shared secret. */ + int point_format; /*!< The format of point export in TLS messages. */ + mbedtls_ecp_point Vi; /*!< The blinding value. */ + mbedtls_ecp_point Vf; /*!< The unblinding value. */ + mbedtls_mpi _d; /*!< The previous \p d. */ } mbedtls_ecdh_context; /** - * \brief Generate a public key. - * Raw function that only does the core computation. + * \brief This function generates an ECDH keypair on an elliptic + * curve. * - * \param grp ECP group - * \param d Destination MPI (secret exponent, aka private key) - * \param Q Destination point (public key) - * \param f_rng RNG function - * \param p_rng RNG parameter + * This function performs the first of two core computations + * implemented during the ECDH key exchange. The second core + * computation is performed by mbedtls_ecdh_compute_shared(). * - * \return 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code + * \param grp The ECP group. + * \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 (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); /** - * \brief Compute shared secret - * Raw function that only does the core computation. + * \brief This function computes the shared secret. * - * \param grp ECP group - * \param z Destination MPI (shared secret) - * \param Q Public key from other party - * \param d Our secret exponent (private key) - * \param f_rng RNG function (see notes) - * \param p_rng RNG parameter + * This function performs the second of two core computations + * implemented during the ECDH key exchange. The first core + * computation is performed by mbedtls_ecdh_gen_public(). * - * \return 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code + * \param grp The ECP group. + * \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 - * 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, 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 ); /** - * \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 ); /** - * \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 ); /** - * \brief Generate a public key and a TLS ServerKeyExchange payload. - * (First function used by a TLS server for ECDHE.) + * \brief This function generates a public key and a TLS + * ServerKeyExchange payload. * - * \param ctx ECDH context - * \param olen number of chars written - * \param buf destination buffer - * \param blen length of buffer - * \param f_rng RNG function - * \param p_rng RNG parameter + * This is the first function used by a TLS server for ECDHE + * ciphersuites. * - * \note This function assumes that ctx->grp has already been - * properly set (for example using mbedtls_ecp_group_load). + * \param ctx The ECDH context. + * \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, 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 ); /** - * \brief Parse and procress a TLS ServerKeyExhange payload. - * (First function used by a TLS client for ECDHE.) + * \brief This function parses and processes a TLS ServerKeyExhange + * payload. * - * \param ctx ECDH context - * \param buf pointer to start of input buffer - * \param end one past end of buffer + * This is the first function used by a TLS client for ECDHE + * ciphersuites. * - * \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, const unsigned char **buf, const unsigned char *end ); /** - * \brief Setup 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.) + * \brief This function sets up an ECDH context from an EC key. * - * \param ctx ECDH constext to set - * \param key EC key to use - * \param side Is it our key (1) or the peer's key (0) ? + * It is used by clients and servers in place of the + * ServerKeyEchange for static ECDH, and imports ECDH + * 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: + * + * + * \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, mbedtls_ecdh_side side ); /** - * \brief Generate a public key and a TLS ClientKeyExchange payload. - * (Second function used by a TLS client for ECDH(E).) + * \brief This function generates a public key and a TLS + * ClientKeyExchange payload. * - * \param ctx ECDH context - * \param olen number of bytes actually written - * \param buf destination buffer - * \param blen size of destination buffer - * \param f_rng RNG function - * \param p_rng RNG parameter + * This is the second function used by a TLS client for ECDH(E) + * ciphersuites. * - * \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, 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 ); /** - * \brief Parse and process a TLS ClientKeyExchange payload. - * (Second function used by a TLS server for ECDH(E).) + * \brief This function parses and processes a TLS ClientKeyExchange + * payload. * - * \param ctx ECDH context - * \param buf start of input buffer - * \param blen length of input buffer + * This is the second function used by a TLS server for ECDH(E) + * ciphersuites. * - * \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, const unsigned char *buf, size_t blen ); /** - * \brief Derive and export the shared secret. - * (Last function used by both TLS client en servers.) + * \brief This function derives and exports the shared secret. * - * \param ctx ECDH context - * \param olen number of bytes written - * \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 + * This is the last function used by both TLS client + * and servers. * - * \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, unsigned char *buf, size_t blen, diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h index 6c6ae294f9..aa23d67f99 100644 --- a/include/mbedtls/ecdsa.h +++ b/include/mbedtls/ecdsa.h @@ -1,10 +1,16 @@ /** * \file ecdsa.h * - * \brief Elliptic curve DSA + * \brief The Elliptic Curve Digital Signature Algorithm (ECDSA). + * + * ECDSA is defined in Standards for Efficient Cryptography Group (SECG): + * SEC1 Elliptic Curve Cryptography. + * The use of ECDSA for TLS is defined in RFC-4492: Elliptic Curve + * Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS). + * */ /* - * 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 * * 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 * 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 #define MBEDTLS_ECDSA_H @@ -28,7 +35,7 @@ #include "md.h" /* - * RFC 4492 page 20: + * RFC-4492 page 20: * * Ecdsa-Sig-Value ::= SEQUENCE { * r INTEGER, @@ -44,11 +51,11 @@ #if MBEDTLS_ECP_MAX_BYTES > 124 #error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN" #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 ) ) /** - * \brief ECDSA context structure + * \brief The ECDSA context structure. */ typedef mbedtls_ecp_keypair mbedtls_ecdsa_context; @@ -57,25 +64,30 @@ extern "C" { #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 r First output integer - * \param s Second output integer - * \param d Private signing key - * \param buf Message hash - * \param blen Length of buf - * \param f_rng RNG function - * \param p_rng RNG parameter + * \param grp The ECP group. + * \param r The first output integer. + * \param s The second output integer. + * \param d The private signing key. + * \param buf The message hash. + * \param blen The length of \p buf. + * \param f_rng The RNG function. + * \param p_rng The RNG parameter. * * \note If the bitlength of the message hash is larger than the - * bitlength of the group order, then the hash is truncated as - * prescribed by SEC1 4.1.3 step 5. + * bitlength of the group order, then the hash is truncated + * as defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography, section + * 4.1.3, step 5. * - * \return 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code + * \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_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, 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) /** - * \brief Compute ECDSA signature of a previously hashed message, - * deterministic version (RFC 6979). + * \brief This function computes the ECDSA signature of a + * previously-hashed message, deterministic version. + * For more information, see RFC-6979: Deterministic + * Usage of the Digital Signature Algorithm (DSA) and Elliptic + * Curve Digital Signature Algorithm (ECDSA). * - * \param grp ECP group - * \param r First output integer - * \param s Second output integer - * \param d Private signing key - * \param buf Message hash - * \param blen Length of buf - * \param md_alg MD algorithm used to hash the message + * \param grp The ECP group. + * \param r The first output integer. + * \param s The second output integer. + * \param d The private signing key. + * \param buf The message hash. + * \param blen The length of \p buf. + * \param md_alg The MD algorithm used to hash the message. * * \note If the bitlength of the message hash is larger than the * bitlength of the group order, then the hash is truncated as - * prescribed by SEC1 4.1.3 step 5. + * defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography, section + * 4.1.3, step 5. * - * \return 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code + * \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_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, 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 */ /** - * \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 buf Message hash - * \param blen Length of buf - * \param Q Public key to use for verification - * \param r First integer of the signature - * \param s Second integer of the signature + * \param grp The ECP group. + * \param buf The message hash. + * \param blen The length of \p buf. + * \param Q The public key to use for verification. + * \param r The first integer of the signature. + * \param s The second integer of the signature. * * \note If the bitlength of the message hash is larger than the * bitlength of the group order, then the hash is truncated as - * prescribed by SEC1 4.1.4 step 3. + * defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography, section + * 4.1.4, step 3. * - * \return 0 if successful, - * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code + * \return \c 0 on success, + * #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid, + * 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, const unsigned char *buf, size_t blen, const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s); /** - * \brief Compute ECDSA signature and write it to buffer, - * serialized as defined in RFC 4492 page 20. - * (Not thread-safe to use same context in multiple threads) + * \brief This function computes the ECDSA signature and writes it + * to a buffer, serialized as defined in RFC-4492: + * Elliptic Curve Cryptography (ECC) Cipher Suites for + * Transport Layer Security (TLS). * - * \note The deterministic version (RFC 6979) is used if - * MBEDTLS_ECDSA_DETERMINISTIC is defined. + * \warning It is not thread-safe to use the same context in + * multiple threads. * - * \param ctx ECDSA context - * \param md_alg Algorithm that was used to hash the message - * \param hash Message hash - * \param hlen Length of hash - * \param sig Buffer that will hold the signature - * \param slen Length of the signature written - * \param f_rng RNG function - * \param p_rng RNG parameter + * \note The deterministic version is used if + * #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more + * information, see RFC-6979: Deterministic Usage + * of the Digital Signature Algorithm (DSA) and Elliptic + * Curve Digital Signature Algorithm (ECDSA). * - * \note The "sig" buffer must be at least as large as twice the - * size of the curve used, plus 9 (eg. 73 bytes if a 256-bit - * curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe. + * \param ctx The ECDSA context. + * \param md_alg The message digest that was used to hash the message. + * \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 * bitlength of the group order, then the hash is truncated as - * prescribed by SEC1 4.1.3 step 5. + * defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography, section + * 4.1.3, step 5. * - * \return 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or - * MBEDTLS_ERR_ASN1_XXX error code + * \return \c 0 on success, + * or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or + * \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, 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 #endif /** - * \brief Compute ECDSA signature and write it to buffer, - * serialized as defined in RFC 4492 page 20. - * Deterministic version, RFC 6979. - * (Not thread-safe to use same context in multiple threads) + * \brief This function computes an ECDSA signature and writes it to a buffer, + * serialized as defined in RFC-4492: Elliptic Curve Cryptography + * (ECC) Cipher Suites for Transport Layer Security (TLS). + * + * The deterministic version is defined in RFC-6979: + * Deterministic Usage of the Digital Signature Algorithm (DSA) and + * Elliptic Curve Digital Signature Algorithm (ECDSA). + * + * \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 * - * \param ctx ECDSA context - * \param hash Message hash - * \param hlen Length of hash - * \param sig Buffer that will hold the signature - * \param slen Length of the signature written - * \param md_alg MD algorithm used to hash the message + * \param ctx The ECDSA context. + * \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 md_alg The MD algorithm used to hash the message. * - * \note The "sig" buffer must be at least as large as twice the - * size of the curve used, plus 9 (eg. 73 bytes if a 256-bit - * curve is used). MBEDTLS_ECDSA_MAX_LEN is always safe. + * \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 * bitlength of the group order, then the hash is truncated as - * prescribed by SEC1 4.1.3 step 5. + * defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography, section + * 4.1.3, step 5. * - * \return 0 if successful, - * or a MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or - * MBEDTLS_ERR_ASN1_XXX error code + * \return \c 0 on success, + * or an \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or + * \c MBEDTLS_ERR_ASN1_XXX error code on failure. + * + * \see ecp.h */ int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx, 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 */ /** - * \brief Read and verify an ECDSA signature + * \brief This function reads and verifies an ECDSA signature. * - * \param ctx ECDSA context - * \param hash Message hash - * \param hlen Size of hash - * \param sig Signature to read and verify - * \param slen Size of sig + * \param ctx The ECDSA context. + * \param hash The message hash. + * \param hlen The size of the hash. + * \param sig The signature to read and verify. + * \param slen The size of \p sig. * * \note If the bitlength of the message hash is larger than the * bitlength of the group order, then the hash is truncated as - * prescribed by SEC1 4.1.4 step 3. + * defined in Standards for Efficient Cryptography Group + * (SECG): SEC1 Elliptic Curve Cryptography, section + * 4.1.4, step 3. * - * \return 0 if successful, - * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid, - * MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is - * valid but its actual length is less than siglen, - * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX error code + * \return \c 0 on success, + * #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid, + * #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is + * valid but its actual length is less than \p siglen, + * 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, const unsigned char *hash, size_t hlen, 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 gid Group (elliptic curve) to use. One of the various - * MBEDTLS_ECP_DP_XXX macros depending on configuration. - * \param f_rng RNG function - * \param p_rng RNG parameter + * \param ctx The ECDSA context to store the keypair in. + * \param gid The elliptic curve to use. One of the various + * \c MBEDTLS_ECP_DP_XXX macros depending on configuration. + * \param f_rng The RNG function. + * \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 (*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 key EC key to use + * \param ctx The ECDSA context to set. + * \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 ); /** - * \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 ); /** - * \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 ); diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h index c7f01c316f..1e5a507a26 100644 --- a/include/mbedtls/gcm.h +++ b/include/mbedtls/gcm.h @@ -1,10 +1,16 @@ /** * \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 D. McGrew, J. Viega, The Galois/Counter Mode of Operation + * (GCM), Natl. Inst. Stand. Technol. + * + * For more information on GCM, see NIST SP 800-38D: Recommendation for + * Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC. + * */ /* - * 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 * * 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 * 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 #define MBEDTLS_GCM_H @@ -42,39 +49,49 @@ extern "C" { #endif /** - * \brief GCM context structure + * \brief The GCM context structure. */ typedef struct { - mbedtls_cipher_context_t cipher_ctx;/*!< cipher context used */ - uint64_t HL[16]; /*!< Precalculated HTable */ - uint64_t HH[16]; /*!< Precalculated HTable */ - uint64_t len; /*!< Total data length */ - uint64_t add_len; /*!< Total add length */ - unsigned char base_ectr[16];/*!< First ECTR for tag */ - unsigned char y[16]; /*!< Y working value */ - unsigned char buf[16]; /*!< buf working value */ - int mode; /*!< Encrypt or Decrypt */ + mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */ + uint64_t HL[16]; /*!< Precalculated HTable low. */ + uint64_t HH[16]; /*!< Precalculated HTable high. */ + uint64_t len; /*!< The total length of the encrypted data. */ + uint64_t add_len; /*!< The total length of the additional data. */ + unsigned char base_ectr[16]; /*!< The first ECTR for tag. */ + unsigned char y[16]; /*!< The Y working value. */ + unsigned char buf[16]; /*!< The buf working value. */ + int mode; /*!< The operation to perform: + #MBEDTLS_GCM_ENCRYPT or + #MBEDTLS_GCM_DECRYPT. */ } mbedtls_gcm_context; /** - * \brief Initialize GCM context (just makes references valid) - * Makes the context ready for mbedtls_gcm_setkey() or - * mbedtls_gcm_free(). + * \brief This function initializes the specified GCM context, + * to make references valid, and prepares the context + * 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 ); /** - * \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 cipher cipher to use (a 128-bit block cipher) - * \param key encryption key - * \param keybits must be 128, 192 or 256 + * \param ctx The GCM context to initialize. + * \param cipher The 128-bit block cipher to use. + * \param key The encryption key. + * \param keybits The key size in bits. Valid options are: + * * - * \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, mbedtls_cipher_id_t cipher, @@ -82,26 +99,27 @@ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx, 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. - * On decryption, the output buffer cannot be the same as input buffer. - * If buffers overlap, the output buffer must trail at least 8 bytes + * \note For encryption, the output buffer can be the same as the input buffer. + * 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. * - * \param ctx GCM context - * \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT - * \param length length of the input data - * \param iv initialization vector - * \param iv_len length of IV - * \param add additional data - * \param add_len length of additional data - * \param input buffer holding the input data - * \param output buffer for holding the output data - * \param tag_len length of the tag to generate - * \param tag buffer for holding the tag + * \param ctx The GCM context to use for encryption or decryption. + * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or + * #MBEDTLS_GCM_DECRYPT. + * \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 The initialization vector. + * \param iv_len The length of the IV. + * \param add The buffer holding the additional data. + * \param add_len The length of the additional data. + * \param input The buffer holding the input data. + * \param output The buffer for holding the output data. + * \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 mode, @@ -116,25 +134,26 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx, 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. - * If buffers overlap, the output buffer must trail at least 8 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. * - * \param ctx GCM context - * \param length length of the input data - * \param iv initialization vector - * \param iv_len length of IV - * \param add additional data - * \param add_len length of additional data - * \param tag buffer holding the tag - * \param tag_len length of the tag - * \param input buffer holding the input data - * \param output buffer for holding the output data + * \param ctx The GCM context. + * \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 The initialization vector. + * \param iv_len The length of the IV. + * \param add The buffer holding the additional data. + * \param add_len The length of the additional data. + * \param tag The buffer holding the tag. + * \param tag_len The length of the tag. + * \param input The buffer holding the input data. + * \param output The buffer for holding the output data. * - * \return 0 if successful and authenticated, - * MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match + * \return 0 if successful and authenticated, or + * #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match. */ int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx, size_t length, @@ -148,16 +167,18 @@ int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx, unsigned char *output ); /** - * \brief Generic GCM stream start function + * \brief This function starts a GCM encryption or decryption + * operation. * - * \param ctx GCM context - * \param mode MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT - * \param iv initialization vector - * \param iv_len length of IV - * \param add additional data (or NULL if length is 0) - * \param add_len length of additional data + * \param ctx The GCM context. + * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or + * #MBEDTLS_GCM_DECRYPT. + * \param iv The initialization vector. + * \param iv_len The length of the IV. + * \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 mode, @@ -167,21 +188,23 @@ int mbedtls_gcm_starts( mbedtls_gcm_context *ctx, size_t add_len ); /** - * \brief Generic GCM update function. Encrypts/decrypts using the - * given GCM context. Expects input to be a multiple of 16 - * bytes! Only the last call before mbedtls_gcm_finish() can be less - * than 16 bytes! + * \brief This function feeds an input buffer into an ongoing GCM + * encryption or decryption operation. * - * \note On decryption, the output buffer cannot be the same as input buffer. - * If buffers overlap, the output buffer must trail at least 8 bytes + * ` The function expects input to be a multiple of 16 + * 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. * - * \param ctx GCM context - * \param length length of the input data - * \param input buffer holding the input data - * \param output buffer for holding the output data + * \param ctx The GCM context. + * \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 The buffer holding the input 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, size_t length, @@ -189,24 +212,27 @@ int mbedtls_gcm_update( mbedtls_gcm_context *ctx, unsigned char *output ); /** - * \brief Generic GCM finalisation function. Wraps up the GCM stream - * and generates the tag. The tag can have a maximum length of - * 16 bytes. + * \brief This function finishes the GCM operation and generates + * the authentication tag. * - * \param ctx GCM context - * \param tag buffer for holding the tag - * \param tag_len length of the tag to generate (must be at least 4) + * It wraps up the GCM stream, and generates the + * tag. The tag can have a maximum length of 16 Bytes. * - * \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, unsigned char *tag, 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 ); @@ -223,9 +249,9 @@ extern "C" { #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 ); diff --git a/include/mbedtls/md.h b/include/mbedtls/md.h index 57c27a6f02..5e0376c05b 100644 --- a/include/mbedtls/md.h +++ b/include/mbedtls/md.h @@ -1,12 +1,12 @@ -/** + /** * \file md.h * - * \brief Generic message digest wrapper + * \brief The generic message-digest wrapper. * * \author Adriaan de Jong */ /* - * 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 * * 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 * 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 #define MBEDTLS_MD_H @@ -64,65 +65,79 @@ typedef enum { #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; /** - * Generic message digest context. + * The generic message-digest context. */ typedef struct { - /** Information about the associated message digest */ + /** Information about the associated message digest. */ const mbedtls_md_info_t *md_info; - /** Digest-specific context */ + /** The digest-specific context. */ void *md_ctx; - /** HMAC part of the context */ + /** The HMAC part of the context. */ void *hmac_ctx; } 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 - * is 0. + * \return A statically allocated array of digests. Each element + * 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 ); /** - * \brief Returns the message digest information associated with the - * given digest name. + * \brief This function returns the message-digest information + * 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 - * NULL if not found. + * \return The message-digest information associated with \p md_name, + * or NULL if not found. */ const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name ); /** - * \brief Returns the message digest information associated with the - * given digest type. + * \brief This function returns the message-digest information + * 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 - * NULL if not found. + * \return The message-digest information associated with \p md_type, + * or NULL if not found. */ const mbedtls_md_info_t *mbedtls_md_info_from_type( mbedtls_md_type_t md_type ); /** - * \brief Initialize a md_context (as NONE) - * This should always be called first. - * Prepares the context for mbedtls_md_setup() or mbedtls_md_free(). + * \brief This function initializes a message-digest context without + * binding it to a particular message-digest algorithm. + * + * 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 ); /** - * \brief Free and clear the internal structures of ctx. - * Can be called at any time after mbedtls_md_init(). - * Mandatory once mbedtls_md_setup() has been called. + * \brief This function clears the internal structure of \p ctx and + * frees any embedded internal structure, but does not free + * \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 ); @@ -133,220 +148,288 @@ void mbedtls_md_free( mbedtls_md_context_t *ctx ); #define MBEDTLS_DEPRECATED #endif /** - * \brief Select MD to use and allocate internal structures. - * Should be called after mbedtls_md_init() or mbedtls_md_free(). + * \brief This function selects the message digest algorithm to use, + * 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. * * \deprecated Superseded by mbedtls_md_setup() in 2.0.0 * - * \param ctx Context to set up. - * \param md_info Message digest to use. + * \param ctx The context to set up. + * \param md_info The information structure of the message-digest algorithm + * to use. * * \returns \c 0 on success, - * \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, - * \c MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure. + * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter 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; #undef MBEDTLS_DEPRECATED #endif /* MBEDTLS_DEPRECATED_REMOVED */ /** - * \brief Select MD to use and allocate internal structures. - * Should be called after mbedtls_md_init() or mbedtls_md_free(). - * Makes it necessary to call mbedtls_md_free() later. + * \brief This function selects the message digest algorithm to use, + * and allocates internal structures. * - * \param ctx Context to set up. - * \param md_info Message digest to use. - * \param hmac 0 to save some memory if HMAC will not be used, - * non-zero is HMAC is going to be used with this context. + * It should be called after mbedtls_md_init() or + * mbedtls_md_free(). Makes it necessary to call + * mbedtls_md_free() later. + * + * \param ctx The context to set up. + * \param md_info The information structure of the message-digest algorithm + * to use. + * \param hmac
  • 0: HMAC is not used. Saves some memory.
    • + *
  • non-zero: HMAC is used with this context.
* * \returns \c 0 on success, - * \c MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, - * \c MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure. + * #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure, or + * #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 ); /** - * \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 - * (cloning from SHA-256 to SHA-512 make no sense). + * \note You must call mbedtls_md_setup() on \c dst before calling + * 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 - * \param src The context to be cloned + * \warning This function clones the message-digest state, not the + * HMAC state. + * + * \param dst The destination context. + * \param src The context to be cloned. * * \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, 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 ); /** - * \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 ); /** - * \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 ); /** - * \brief Prepare the context to digest a new message. - * Generally called after mbedtls_md_setup() or mbedtls_md_finish(). - * Followed by mbedtls_md_update(). + * \brief This function starts a message-digest computation. * - * \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 - * verification fails. + * \param ctx The generic message-digest context. + * + * \returns \c 0 on success, #MBEDTLS_ERR_MD_BAD_INPUT_DATA if + * parameter verification fails. */ int mbedtls_md_starts( mbedtls_md_context_t *ctx ); /** - * \brief Generic message digest process buffer - * Called between mbedtls_md_starts() and mbedtls_md_finish(). - * May be called repeatedly. + * \brief This function feeds an input buffer into an ongoing + * message-digest computation. * - * \param ctx Generic message digest context - * \param input buffer holding the datal - * \param ilen length of the input data + * You must call mbedtls_md_starts() before calling this + * function. You may call this function multiple times. + * Afterwards, call mbedtls_md_finish(). * - * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter - * verification fails. + * \param ctx The generic message-digest context. + * \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 ); /** - * \brief Generic message digest final digest - * Called after mbedtls_md_update(). - * Usually followed by mbedtls_md_free() or mbedtls_md_starts(). + * \brief This function finishes the digest operation, + * and writes the result to the output buffer. * - * \param ctx Generic message digest context - * \param output Generic message digest checksum result + * Call this function after a call to mbedtls_md_starts(), + * 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 - * verification fails. + * \param ctx The generic message-digest context. + * \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 ); /** - * \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 - * \param input buffer holding the data - * \param ilen length of the input data - * \param output Generic message digest checksum result + * The result is calculated as + * Output = message_digest(input buffer). * - * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter - * verification fails. + * \param md_info The information structure of the message-digest algorithm + * 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, unsigned char *output ); #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 - * \param path input file name - * \param output generic message digest checksum result + * The result is calculated as + * Output = message_digest(file contents). * - * \return 0 if successful, - * MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed, - * MBEDTLS_ERR_MD_BAD_INPUT_DATA if md_info was NULL. + * \param md_info The information structure of the message-digest algorithm + * to use. + * \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, unsigned char *output ); #endif /* MBEDTLS_FS_IO */ /** - * \brief Set HMAC key and prepare to authenticate a new message. - * Usually called after mbedtls_md_setup() or mbedtls_md_hmac_finish(). + * \brief This function sets the HMAC key and prepares to + * authenticate a new message. * - * \param ctx HMAC context - * \param key HMAC secret key - * \param keylen length of the HMAC key in bytes + * Call this function after mbedtls_md_setup(), to use + * the MD context for an HMAC calculation, then call + * 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 - * verification fails. + * \param ctx The message digest context containing an embedded HMAC + * 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, size_t keylen ); /** - * \brief Generic HMAC process buffer. - * Called between mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset() - * and mbedtls_md_hmac_finish(). - * May be called repeatedly. + * \brief This function feeds an input buffer into an ongoing HMAC + * computation. * - * \param ctx HMAC context - * \param input buffer holding the data - * \param ilen length of the input data + * Call mbedtls_md_hmac_starts() or mbedtls_md_hmac_reset() + * before calling this function. + * 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 - * verification fails. + * \param ctx The message digest context containing an embedded HMAC + * 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, size_t ilen ); /** - * \brief Output HMAC. - * Called after mbedtls_md_hmac_update(). - * Usually followed by mbedtls_md_hmac_reset(), - * mbedtls_md_hmac_starts(), or mbedtls_md_free(). + * \brief This function finishes the HMAC operation, and writes + * the result to the output buffer. * - * \param ctx HMAC context - * \param output Generic HMAC checksum result + * Call this function after mbedtls_md_hmac_starts() and + * 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 - * verification fails. + * \param ctx The message digest context containing an embedded HMAC + * 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); /** - * \brief Prepare to authenticate a new message with the same key. - * Called after mbedtls_md_hmac_finish() and before - * mbedtls_md_hmac_update(). + * \brief This function prepares to authenticate a new message with + * the same key as the previous HMAC operation. * - * \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 - * verification fails. + * \param ctx The message digest context containing an embedded HMAC + * 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 ); /** - * \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 - * \param key HMAC secret key - * \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 + * The function allocates the context, performs the + * calculation, and frees the context. * - * \returns 0 on success, MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter - * verification fails. + * The HMAC result is calculated as + * 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, const unsigned char *input, size_t ilen, diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h index e051751189..ed10775848 100644 --- a/include/mbedtls/platform.h +++ b/include/mbedtls/platform.h @@ -1,10 +1,10 @@ /** * \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 * * 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 * 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 #define MBEDTLS_PLATFORM_H @@ -52,34 +52,34 @@ extern "C" { #include #if !defined(MBEDTLS_PLATFORM_STD_SNPRINTF) #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 -#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 #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 #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 #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 #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 #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 #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 #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 #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 #if defined(MBEDTLS_FS_IO) #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 ); /** - * \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 free_func the free function implementation + * \param calloc_func The \c calloc 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 ), 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, ... ); /** - * \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 *, ... ) ); @@ -163,11 +163,12 @@ int mbedtls_platform_set_fprintf( int (*fprintf_func)( FILE *stream, const char 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 *, ... ) ); #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, ... ); /** - * \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, 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 ); /** - * \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 ) ); #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 ); /** - * \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_write_func the seed writing function implementation + * \param nv_seed_read_func The seed reading 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 (*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) /** - * \brief Platform context structure + * \brief The platform context structure. * * \note This structure may be used to assist platform-specific - * setup/teardown operations. + * setup or teardown operations. */ 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; @@ -307,32 +311,32 @@ mbedtls_platform_context; #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 - * implementation is platform specific, and by default, unless platform - * specific code is provided, it does nothing. + * implementation is platform-specific, and unless + * 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. */ 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 - * been correctly freed using the appropriate free function. - * Its implementation is platform specific, and by default, unless - * platform specific code is provided, it does nothing. + * \note This function should be called after every other Mbed TLS module + * has been correctly freed using the appropriate free function. + * Its implementation is platform-specific, and unless + * 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. */ void mbedtls_platform_teardown( mbedtls_platform_context *ctx ); diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h index 752105822c..fb2f77f94f 100644 --- a/include/mbedtls/rsa.h +++ b/include/mbedtls/rsa.h @@ -1,10 +1,15 @@ /** * \file rsa.h * - * \brief The RSA public-key cryptosystem + * \brief The RSA public-key cryptosystem. + * + * For more information, see Public-Key Cryptography Standards (PKCS) + * #1 v1.5: RSA Encryption and Public-Key Cryptography Standards + * (PKCS) #1 v2.1: RSA Cryptography Specifications. + * */ /* - * 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 * * Licensed under the Apache License, Version 2.0 (the "License"); you may @@ -19,7 +24,7 @@ * See the License for the specific language governing permissions and * 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_RSA_H #define MBEDTLS_RSA_H @@ -43,26 +48,26 @@ #define MBEDTLS_ERR_RSA_BAD_INPUT_DATA -0x4080 /**< Bad input parameters to function. */ #define MBEDTLS_ERR_RSA_INVALID_PADDING -0x4100 /**< Input data contains invalid padding and is rejected. */ #define MBEDTLS_ERR_RSA_KEY_GEN_FAILED -0x4180 /**< Something failed during generation of a key. */ -#define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED -0x4200 /**< Key failed to pass the library's validity check. */ +#define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED -0x4200 /**< Key failed to pass the validity check of the library. */ #define MBEDTLS_ERR_RSA_PUBLIC_FAILED -0x4280 /**< The public key operation failed. */ #define MBEDTLS_ERR_RSA_PRIVATE_FAILED -0x4300 /**< The private key operation failed. */ #define MBEDTLS_ERR_RSA_VERIFY_FAILED -0x4380 /**< The PKCS#1 verification failed. */ #define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE -0x4400 /**< The output buffer for decryption is not large enough. */ #define MBEDTLS_ERR_RSA_RNG_FAILED -0x4480 /**< The random generator failed to generate non-zeros. */ -#define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION -0x4500 /**< The implementation doesn't offer the requested operation, e.g. because of security violations or lack of functionality */ +#define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION -0x4500 /**< The implementation does not offer the requested operation, for example, because of security violations or lack of functionality. */ #define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED -0x4580 /**< RSA hardware accelerator failed. */ /* * RSA constants */ -#define MBEDTLS_RSA_PUBLIC 0 -#define MBEDTLS_RSA_PRIVATE 1 +#define MBEDTLS_RSA_PUBLIC 0 /**< Request private key operation. */ +#define MBEDTLS_RSA_PRIVATE 1 /**< Request public key operation. */ -#define MBEDTLS_RSA_PKCS_V15 0 -#define MBEDTLS_RSA_PKCS_V21 1 +#define MBEDTLS_RSA_PKCS_V15 0 /**< Use PKCS-1 v1.5 encoding. */ +#define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS-1 v2.1 encoding. */ -#define MBEDTLS_RSA_SIGN 1 -#define MBEDTLS_RSA_CRYPT 2 +#define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */ +#define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */ #define MBEDTLS_RSA_SALT_LEN_ANY -1 @@ -80,103 +85,106 @@ extern "C" { #endif /** - * \brief RSA context structure + * \brief The RSA context structure. * * \note Direct manipulation of the members of this structure - * is deprecated and will no longer be supported starting - * from the next major release. All manipulation should instead - * be done through the public interface functions. - * + * is deprecated. All manipulation should instead be done through + * the public interface functions. */ typedef struct { - int ver; /*!< always 0 */ - size_t len; /*!< size(N) in chars */ + int ver; /*!< Always 0.*/ + size_t len; /*!< The size of \p N in Bytes. */ - mbedtls_mpi N; /*!< public modulus */ - mbedtls_mpi E; /*!< public exponent */ + mbedtls_mpi N; /*!< The public modulus. */ + mbedtls_mpi E; /*!< The public exponent. */ - mbedtls_mpi D; /*!< private exponent */ - mbedtls_mpi P; /*!< 1st prime factor */ - mbedtls_mpi Q; /*!< 2nd prime factor */ + mbedtls_mpi D; /*!< The private exponent. */ + mbedtls_mpi P; /*!< The first prime factor. */ + mbedtls_mpi Q; /*!< The second prime factor. */ - mbedtls_mpi DP; /*!< D % (P - 1) */ - mbedtls_mpi DQ; /*!< D % (Q - 1) */ + mbedtls_mpi DP; /*!< \p D % (P - 1) */ + mbedtls_mpi DQ; /*!< \p D % (Q - 1) */ mbedtls_mpi QP; /*!< 1 / (Q % P) */ - mbedtls_mpi RN; /*!< cached R^2 mod N */ + mbedtls_mpi RN; /*!< cached R^2 mod \p N */ - mbedtls_mpi RP; /*!< cached R^2 mod P */ - mbedtls_mpi RQ; /*!< cached R^2 mod Q */ + mbedtls_mpi RP; /*!< cached R^2 mod \p P */ + mbedtls_mpi RQ; /*!< cached R^2 mod \p Q */ - mbedtls_mpi Vi; /*!< cached blinding value */ - mbedtls_mpi Vf; /*!< cached un-blinding value */ + mbedtls_mpi Vi; /*!< The cached blinding value. */ + mbedtls_mpi Vf; /*!< The cached un-blinding value. */ - int padding; /*!< \c MBEDTLS_RSA_PKCS_V15 for 1.5 padding and - \c MBEDTLS_RSA_PKCS_v21 for OAEP/PSS */ - int hash_id; /*!< Hash identifier of mbedtls_md_type_t as - specified in the mbedtls_md.h header file - for the EME-OAEP and EMSA-PSS - encoding */ + int padding; /*!< Selects padding mode: + #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and + #MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */ + int hash_id; /*!< Hash identifier of mbedtls_md_type_t type, + as specified in md.h for use in the MGF + mask generating function used in the + EME-OAEP and EMSA-PSS encodings. */ #if defined(MBEDTLS_THREADING_C) - mbedtls_threading_mutex_t mutex; /*!< Thread-safety mutex */ + mbedtls_threading_mutex_t mutex; /*!< Thread-safety mutex. */ #endif } mbedtls_rsa_context; /** - * \brief Initialize an RSA context + * \brief This function initializes an RSA context. * - * Note: Set padding to \c MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP + * \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP * encryption scheme and the RSASSA-PSS signature scheme. * - * \param ctx RSA context to be initialized - * \param padding \c MBEDTLS_RSA_PKCS_V15 or \c MBEDTLS_RSA_PKCS_V21 - * \param hash_id \c MBEDTLS_RSA_PKCS_V21 hash identifier + * \param ctx The RSA context to initialize. + * \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or + * #MBEDTLS_RSA_PKCS_V21. + * \param hash_id The hash identifier of #mbedtls_md_type_t type, if + * \p padding is #MBEDTLS_RSA_PKCS_V21. * - * \note The hash_id parameter is actually ignored - * when using \c MBEDTLS_RSA_PKCS_V15 padding. + * \note The \p hash_id parameter is ignored when using + * #MBEDTLS_RSA_PKCS_V15 padding. * - * \note Choice of padding mode is strictly enforced for private key + * \note The choice of padding mode is strictly enforced for private key * operations, since there might be security concerns in - * mixing padding modes. For public key operations it's merely + * mixing padding modes. For public key operations it is * a default value, which can be overriden by calling specific - * rsa_rsaes_xxx or rsa_rsassa_xxx functions. + * \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions. * - * \note The chosen hash is always used for OEAP encryption. - * For PSS signatures, it's always used for making signatures, - * but can be overriden (and always is, if set to - * \c MBEDTLS_MD_NONE) for verifying them. + * \note The hash selected in \p hash_id is always used for OEAP + * encryption. For PSS signatures, it is always used for + * making signatures, but can be overriden for verifying them. + * If set to #MBEDTLS_MD_NONE, it is always overriden. */ void mbedtls_rsa_init( mbedtls_rsa_context *ctx, int padding, int hash_id); /** - * \brief Import a set of core parameters into an RSA context + * \brief This function imports a set of core parameters into an + * RSA context. * - * \param ctx Initialized RSA context to store parameters - * \param N RSA modulus, or NULL - * \param P First prime factor of N, or NULL - * \param Q Second prime factor of N, or NULL - * \param D Private exponent, or NULL - * \param E Public exponent, or NULL + * \param ctx The initialized RSA context to store the parameters in. + * \param N The RSA modulus, or NULL. + * \param P The first prime factor of \p N, or NULL. + * \param Q The second prime factor of \p N, or NULL. + * \param D The private exponent, or NULL. + * \param E The public exponent, or NULL. * * \note This function can be called multiple times for successive - * imports if the parameters are not simultaneously present. + * imports, if the parameters are not simultaneously present. + * * Any sequence of calls to this function should be followed - * by a call to \c mbedtls_rsa_complete which will check - * and complete the provided information to a ready-for-use + * by a call to mbedtls_rsa_complete(), which checks and + * completes the provided information to a ready-for-use * public or private RSA key. * - * \note See the documentation of \c mbedtls_rsa_complete for more - * information on which parameters are necessary to setup - * a private or public RSA key. + * \note See mbedtls_rsa_complete() for more information on which + * parameters are necessary to set up a private or public + * RSA key. * * \note The imported parameters are copied and need not be preserved * for the lifetime of the RSA context being set up. * - * \return 0 if successful, non-zero error code on failure. + * \return \c 0 on success, or a non-zero error code on failure. */ int mbedtls_rsa_import( mbedtls_rsa_context *ctx, const mbedtls_mpi *N, @@ -184,36 +192,37 @@ int mbedtls_rsa_import( mbedtls_rsa_context *ctx, const mbedtls_mpi *D, const mbedtls_mpi *E ); /** - * \brief Import core RSA parameters in raw big-endian - * binary format into an RSA context + * \brief This function imports core RSA parameters, in raw big-endian + * binary format, into an RSA context. * - * \param ctx Initialized RSA context to store parameters - * \param N RSA modulus, or NULL - * \param N_len Byte length of N, ignored if N == NULL - * \param P First prime factor of N, or NULL - * \param P_len Byte length of P, ignored if P == NULL - * \param Q Second prime factor of N, or NULL - * \param Q_len Byte length of Q, ignored if Q == NULL - * \param D Private exponent, or NULL - * \param D_len Byte length of D, ignored if D == NULL - * \param E Public exponent, or NULL - * \param E_len Byte length of E, ignored if E == NULL + * \param ctx The initialized RSA context to store the parameters in. + * \param N The RSA modulus, or NULL. + * \param N_len The Byte length of \p N, ignored if \p N == NULL. + * \param P The first prime factor of \p N, or NULL. + * \param P_len The Byte length of \p P, ignored if \p P == NULL. + * \param Q The second prime factor of \p N, or NULL. + * \param Q_len The Byte length of \p Q, ignored if \p Q == NULL. + * \param D The private exponent, or NULL. + * \param D_len The Byte length of \p D, ignored if \p D == NULL. + * \param E The public exponent, or NULL. + * \param E_len The Byte length of \p E, ignored if \p E == NULL. * * \note This function can be called multiple times for successive - * imports if the parameters are not simultaneously present. + * imports, if the parameters are not simultaneously present. + * * Any sequence of calls to this function should be followed - * by a call to \c mbedtls_rsa_complete which will check - * and complete the provided information to a ready-for-use + * by a call to mbedtls_rsa_complete(), which checks and + * completes the provided information to a ready-for-use * public or private RSA key. * - * \note See the documentation of \c mbedtls_rsa_complete for more - * information on which parameters are necessary to setup - * a private or public RSA key. + * \note See mbedtls_rsa_complete() for more information on which + * parameters are necessary to set up a private or public + * RSA key. * * \note The imported parameters are copied and need not be preserved * for the lifetime of the RSA context being set up. * - * \return 0 if successful, non-zero error code on failure. + * \return \c 0 on success, or a non-zero error code on failure. */ int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx, unsigned char const *N, size_t N_len, @@ -223,71 +232,71 @@ int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx, unsigned char const *E, size_t E_len ); /** - * \brief Attempt to complete an RSA context from + * \brief This function completes an RSA context from * a set of imported core parameters. * - * \param ctx Initialized RSA context to store parameters + * To setup an RSA public key, precisely \p N and \p E + * must have been imported. * - * \note - * - To setup an RSA public key, precisely N and E - * must have been imported. + * To setup an RSA private key, sufficient information must + * be present for the other parameters to be derivable. * - * - To setup an RSA private key, enough information must be - * present for the other parameters to be derivable. + * The default implementation supports the following: + *
  • Derive \p P, \p Q from \p N, \p D, \p E.
    • + *
  • Derive \p N, \p D from \p P, \p Q, \p E.
+ * Alternative implementations need not support these. * - * The default implementation supports the following: - * - Derive P, Q from N, D, E - * - Derive N, D from P, Q, E. + * If this function runs successfully, it guarantees that + * the RSA context can be used for RSA operations without + * the risk of failure or crash. * - * - Alternative implementations need not support these - * and may return \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA instead. + * \param ctx The initialized RSA context holding imported parameters. * - * \return - * - 0 if successful. In this case, it is guaranteed - * that the RSA context can be used for RSA operations - * without the risk of failure or crash. - * - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted - * derivations failed. + * \return \c 0 on success, or #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the + * attempted derivations failed. * * \warning This function need not perform consistency checks - * for the imported parameters! In particular, parameters that - * are not needed by the implementation may be silently discarded - * and left unchecked. For the purpose of checking the consistency - * of the key material, see \c mbedtls_rsa_check_privkey. + * for the imported parameters. In particular, parameters that + * are not needed by the implementation might be silently + * discarded and left unchecked. To check the consistency + * of the key material, see mbedtls_rsa_check_privkey(). * */ int mbedtls_rsa_complete( mbedtls_rsa_context *ctx ); /** - * \brief Export core parameters of an RSA key + * \brief This function exports the core parameters of an RSA key. * - * \param ctx Initialized RSA context - * \param N MPI to hold the RSA modulus, or NULL - * \param P MPI to hold the first prime factor of N, or NULL - * \param Q MPI to hold the second prime factor of N, or NULL - * \param D MPI to hold the private exponent, or NULL - * \param E MPI to hold the public exponent, or NULL + * If this function runs successfully, the non-NULL buffers + * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully + * written, with additional unused space filled leading by + * zero Bytes. * - * \return - * - 0 if successful. In this case, the non-NULL buffers - * pointed to by N, P, Q, D, E are fully written, with - * additional unused space filled leading by 0-bytes. - * - Non-zero return code otherwise. In particular, if - * exporting the requested parameters - * cannot be done because of a lack of functionality - * or because of security policies, the error code - * \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION is returned. - * In this case, the RSA context stays intact and can - * be continued to be used. + * Possible reasons for returning + * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:
    + *
  • An alternative RSA implementation is in use, which + * stores the key externally, and either cannot or should + * not export it into RAM.
    • + *
  • A SW or HW implementation might not support a certain + * deduction. For example, \p P, \p Q from \p N, \p D, + * and \p E if the former are not part of the + * implementation.
* - * \note Reasons for returning \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION - * would be the following: Firstly, it might be that an - * alternative RSA implementation is in use which stores - * the key externally, and which either cannot or should not - * export it into RAM. Alternatively, an implementation - * (regardless of SW or HW) might not support deducing e.g. - * P, Q from N, D, E if the former are not part of the - * implementation. + * If the function fails due to an unsupported operation, + * the RSA context stays intact and remains usable. + * + * \param ctx The initialized RSA context. + * \param N The MPI to hold the RSA modulus, or NULL. + * \param P The MPI to hold the first prime factor of \p N, or NULL. + * \param Q The MPI to hold the second prime factor of \p N, or NULL. + * \param D The MPI to hold the private exponent, or NULL. + * \param E The MPI to hold the public exponent, or NULL. + * + * \return \c 0 on success, + * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the + * requested parameters cannot be done due to missing + * functionality or because of security policies, + * or a non-zero return code on any other failure. * */ int mbedtls_rsa_export( const mbedtls_rsa_context *ctx, @@ -295,46 +304,48 @@ int mbedtls_rsa_export( const mbedtls_rsa_context *ctx, mbedtls_mpi *D, mbedtls_mpi *E ); /** - * \brief Export core parameters of an RSA key - * in raw big-endian binary format + * \brief This function exports core parameters of an RSA key + * in raw big-endian binary format. * - * \param ctx Initialized RSA context - * \param N Byte array to store the RSA modulus, or NULL - * \param N_len Size of buffer for modulus - * \param P Byte array to hold the first prime factor of N, or NULL - * \param P_len Size of buffer for first prime factor - * \param Q Byte array to hold the second prime factor of N, or NULL - * \param Q_len Size of buffer for second prime factor - * \param D Byte array to hold the private exponent, or NULL - * \param D_len Size of buffer for private exponent - * \param E Byte array to hold the public exponent, or NULL - * \param E_len Size of buffer for public exponent + * If this function runs successfully, the non-NULL buffers + * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully + * written, with additional unused space filled leading by + * zero Bytes. + * + * Possible reasons for returning + * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:
    + *
  • An alternative RSA implementation is in use, which + * stores the key externally, and either cannot or should + * not export it into RAM.
    • + *
  • A SW or HW implementation might not support a certain + * deduction. For example, \p P, \p Q from \p N, \p D, + * and \p E if the former are not part of the + * implementation.
+ * If the function fails due to an unsupported operation, + * the RSA context stays intact and remains usable. + * + * \param ctx The initialized RSA context. + * \param N The Byte array to store the RSA modulus, or NULL. + * \param N_len The size of the buffer for the modulus. + * \param P The Byte array to hold the first prime factor of \p N, or + * NULL. + * \param P_len The size of the buffer for the first prime factor. + * \param Q The Byte array to hold the second prime factor of \p N, or + NULL. + * \param Q_len The size of the buffer for the second prime factor. + * \param D The Byte array to hold the private exponent, or NULL. + * \param D_len The size of the buffer for the private exponent. + * \param E The Byte array to hold the public exponent, or NULL. + * \param E_len The size of the buffer for the public exponent. * * \note The length fields are ignored if the corresponding * buffer pointers are NULL. * - * \return - * - 0 if successful. In this case, the non-NULL buffers - * pointed to by N, P, Q, D, E are fully written, with - * additional unused space filled leading by 0-bytes. - * - Non-zero return code otherwise. In particular, if - * exporting the requested parameters - * cannot be done because of a lack of functionality - * or because of security policies, the error code - * \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION is returned. - * In this case, the RSA context stays intact and can - * be continued to be used. - * - * \note Reasons for returning \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION - * would be the following: Firstly, it might be that an - * alternative RSA implementation is in use which stores - * the key externally, and which either cannot or should not - * export it into RAM. Alternatively, an implementation - * (regardless of SW or HW) might not support deducing e.g. - * P, Q from N, D, E if the former are not part of the - * implementation. - * - * + * \return \c 0 on success, + * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the + * requested parameters cannot be done due to missing + * functionality or because of security policies, + * or a non-zero return code on any other failure. */ int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx, unsigned char *N, size_t N_len, @@ -344,57 +355,59 @@ int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx, unsigned char *E, size_t E_len ); /** - * \brief Export CRT parameters of a private RSA key + * \brief This function exports CRT parameters of a private RSA key. * - * \param ctx Initialized RSA context - * \param DP MPI to hold D modulo P-1, or NULL - * \param DQ MPI to hold D modulo Q-1, or NULL - * \param QP MPI to hold modular inverse of Q modulo P, or NULL + * \param ctx The initialized RSA context. + * \param DP The MPI to hold D modulo P-1, or NULL. + * \param DQ The MPI to hold D modulo Q-1, or NULL. + * \param QP The MPI to hold modular inverse of Q modulo P, or NULL. * - * \return 0 if successful, non-zero error code otherwise. + * \return \c 0 on success, non-zero error code otherwise. * * \note Alternative RSA implementations not using CRT-parameters - * internally can implement this function using based on - * \c mbedtls_rsa_deduce_opt. + * internally can implement this function based on + * mbedtls_rsa_deduce_opt(). * */ int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx, mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP ); /** - * \brief Set padding for an already initialized RSA context - * See \c mbedtls_rsa_init() for details. + * \brief This function sets padding for an already initialized RSA + * context. See mbedtls_rsa_init() for details. * - * \param ctx RSA context to be set - * \param padding \c MBEDTLS_RSA_PKCS_V15 or \c MBEDTLS_RSA_PKCS_V21 - * \param hash_id \c MBEDTLS_RSA_PKCS_V21 hash identifier + * \param ctx The RSA context to be set. + * \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or + * #MBEDTLS_RSA_PKCS_V21. + * \param hash_id The #MBEDTLS_RSA_PKCS_V21 hash identifier. */ void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding, int hash_id); /** - * \brief Get length of RSA modulus in bytes + * \brief This function retrieves the length of RSA modulus in Bytes. * - * \param ctx Initialized RSA context + * \param ctx The initialized RSA context. * - * \return Length of RSA modulus, in bytes. + * \return The length of the RSA modulus in Bytes. * */ size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx ); /** - * \brief Generate an RSA keypair + * \brief This function generates an RSA keypair. * - * \param ctx RSA context that will hold the key - * \param f_rng RNG function - * \param p_rng RNG parameter - * \param nbits size of the public key in bits - * \param exponent public exponent (e.g., 65537) + * \param ctx The RSA context used to hold the key. + * \param f_rng The RNG function. + * \param p_rng The RNG parameter. + * \param nbits The size of the public key in bits. + * \param exponent The public exponent. For example, 65537. * - * \note mbedtls_rsa_init() must be called beforehand to setup - * the RSA context. + * \note mbedtls_rsa_init() must be called before this function, + * to set up the RSA context. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + on failure. */ int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -402,101 +415,109 @@ int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx, unsigned int nbits, int exponent ); /** - * \brief Check if a context contains (at least) an RSA public key + * \brief This function checks if a context contains at least an RSA + * public key. * - * \param ctx RSA context to be checked + * If the function runs successfully, it is guaranteed that + * enough information is present to perform an RSA public key + * operation using mbedtls_rsa_public(). * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code. - * On success, it is guaranteed that enough information is - * present to perform an RSA public key operation - * \c mbedtls_rsa_public. + * \param ctx The RSA context to check. + * + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * */ int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx ); /** - * \brief Check if a context contains an RSA private key + * \brief This function checks if a context contains an RSA private key * and perform basic consistency checks. * - * \param ctx RSA context to be checked + * \param ctx The RSA context to check. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code. + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code on + * failure. * * \note The consistency checks performed by this function not only - * ensure that \c mbedtls_rsa_private can be called successfully + * ensure that mbedtls_rsa_private() can be called successfully * on the given context, but that the various parameters are * mutually consistent with high probability, in the sense that - * \c mbedtls_rsa_public and \c mbedtls_rsa_private are inverses. + * mbedtls_rsa_public() and mbedtls_rsa_private() are inverses. * * \warning This function should catch accidental misconfigurations * like swapping of parameters, but it cannot establish full * trust in neither the quality nor the consistency of the key * material that was used to setup the given RSA context: - * - Regarding consistency, note (see \c mbedtls_rsa_complete) - * that imported parameters irrelevant for the implementation - * might be silently dropped, in which case the present - * function doesn't have access to and hence cannot check them. - * If you want to check the consistency of the entire - * content of, say, an PKCS1-encoded RSA private key, you - * should use \c mbedtls_rsa_validate_params before setting - * up the RSA context. - * Further, if the implementation performs empirical checks, - * these checks will substantiate but not guarantee consistency. - * - Regarding quality, this function is not expected to perform - * extended quality assessments like checking that the prime - * factors are safe. Further, it is the user's responsibility to - * ensure trustworthiness of the source of his RSA parameters, - * a question going beyond what's effectively checkable - * by the library. - * + *
  • Consistency: Imported parameters that are irrelevant + * for the implementation might be silently dropped. If dropped, + * the current function does not have access to them, + * and therefore cannot check them. See mbedtls_rsa_complete(). + * If you want to check the consistency of the entire + * content of an PKCS1-encoded RSA private key, for example, you + * should use mbedtls_rsa_validate_params() before setting + * up the RSA context. + * Additionally, if the implementation performs empirical checks, + * these checks substantiate but do not guarantee consistency.
    • + *
  • Quality: This function is not expected to perform + * extended quality assessments like checking that the prime + * factors are safe. Additionally, it is the responsibility of the + * user to ensure the trustworthiness of the source of his RSA + * parameters, which goes beyond what is effectively checkable + * by the library.
*/ int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx ); /** - * \brief Check a public-private RSA key pair. - * Check each of the contexts, and make sure they match. + * \brief This function checks a public-private RSA key pair. * - * \param pub RSA context holding the public key - * \param prv RSA context holding the private key + * It checks each of the contexts, and makes sure they match. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \param pub The RSA context holding the public key. + * \param prv The RSA context holding the private key. + * + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. */ int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub, const mbedtls_rsa_context *prv ); /** - * \brief Do an RSA public key operation + * \brief This function performs an RSA public key operation. * - * \param ctx RSA context - * \param input input buffer - * \param output output buffer + * \param ctx The RSA context. + * \param input The input buffer. + * \param output The output buffer. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \note This function does NOT take care of message - * padding. Also, be sure to set input[0] = 0 or ensure that - * input is smaller than N. + * \note This function does not handle message padding. + * + * \note Make sure to set \p input[0] = 0 or ensure that + * input is smaller than \p N. * * \note The input and output buffers must be large - * enough (eg. 128 bytes if RSA-1024 is used). + * enough. For example, 128 Bytes if RSA-1024 is used. */ int mbedtls_rsa_public( mbedtls_rsa_context *ctx, const unsigned char *input, unsigned char *output ); /** - * \brief Do an RSA private key operation + * \brief This function performs an RSA private key operation. * - * \param ctx RSA context - * \param f_rng RNG function (Needed for blinding) - * \param p_rng RNG parameter - * \param input input buffer - * \param output output buffer + * \param ctx The RSA context. + * \param f_rng The RNG function. Needed for blinding. + * \param p_rng The RNG parameter. + * \param input The input buffer. + * \param output The output buffer. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * * \note The input and output buffers must be large - * enough (eg. 128 bytes if RSA-1024 is used). + * enough. For example, 128 Bytes if RSA-1024 is used. */ int mbedtls_rsa_private( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -505,32 +526,36 @@ int mbedtls_rsa_private( mbedtls_rsa_context *ctx, unsigned char *output ); /** - * \brief Generic wrapper to perform a PKCS#1 encryption using the - * mode from the context. Add the message padding, then do an - * RSA operation. + * \brief This function adds the message padding, then performs an RSA + * operation. * - * \param ctx RSA context - * \param f_rng RNG function (Needed for padding and PKCS#1 v2.1 encoding - * and \c MBEDTLS_RSA_PRIVATE) - * \param p_rng RNG parameter - * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE - * \param ilen contains the plaintext length - * \param input buffer holding the data to be encrypted - * \param output buffer that will hold the ciphertext + * It is the generic wrapper for performing a PKCS#1 encryption + * operation using the \p mode from the context. + * + * + * \param ctx The RSA context. + * \param f_rng The RNG function. Needed for padding, PKCS#1 v2.1 + * encoding, and #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param ilen The length of the plaintext. + * \param input The buffer holding the data to encrypt. + * \param output The buffer used to hold the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PUBLIC. + * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library + * are likely to remove the \p mode argument and have it + * implicitly set to #MBEDTLS_RSA_PUBLIC. * * \note Alternative implementations of RSA need not support - * mode being set to MBEDTLS_RSA_PRIVATE and may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \note The output buffer must be as large as the size - * of ctx->N (eg. 128 bytes if RSA-1024 is used). + * \note The input and output buffers must be as large as the size + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. */ int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -540,29 +565,32 @@ int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx, unsigned char *output ); /** - * \brief Perform a PKCS#1 v1.5 encryption (RSAES-PKCS1-v1_5-ENCRYPT) + * \brief This function performs a PKCS#1 v1.5 encryption operation + * (RSAES-PKCS1-v1_5-ENCRYPT). * - * \param ctx RSA context - * \param f_rng RNG function (Needed for padding and \c MBEDTLS_RSA_PRIVATE) - * \param p_rng RNG parameter - * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE - * \param ilen contains the plaintext length - * \param input buffer holding the data to be encrypted - * \param output buffer that will hold the ciphertext + * \param ctx The RSA context. + * \param f_rng The RNG function. Needed for padding and + * #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param ilen The length of the plaintext. + * \param input The buffer holding the data to encrypt. + * \param output The buffer used to hold the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PUBLIC. + * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library + * are likely to remove the \p mode argument and have it + * implicitly set to #MBEDTLS_RSA_PUBLIC. * * \note Alternative implementations of RSA need not support - * mode being set to MBEDTLS_RSA_PRIVATE and may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * * \note The output buffer must be as large as the size - * of ctx->N (eg. 128 bytes if RSA-1024 is used). + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. */ int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -572,32 +600,34 @@ int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx, unsigned char *output ); /** - * \brief Perform a PKCS#1 v2.1 OAEP encryption (RSAES-OAEP-ENCRYPT) + * \brief This function performs a PKCS#1 v2.1 OAEP encryption + * operation (RSAES-OAEP-ENCRYPT). * - * \param ctx RSA context - * \param f_rng RNG function (Needed for padding and PKCS#1 v2.1 encoding - * and \c MBEDTLS_RSA_PRIVATE) - * \param p_rng RNG parameter - * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE - * \param label buffer holding the custom label to use - * \param label_len contains the label length - * \param ilen contains the plaintext length - * \param input buffer holding the data to be encrypted - * \param output buffer that will hold the ciphertext + * \param ctx The RSA context. + * \param f_rng The RNG function. Needed for padding and PKCS#1 v2.1 + * encoding and #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param label The buffer holding the custom label to use. + * \param label_len The length of the label. + * \param ilen The length of the plaintext. + * \param input The buffer holding the data to encrypt. + * \param output The buffer used to hold the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PUBLIC. + * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library + * are likely to remove the \p mode argument and have it + * implicitly set to #MBEDTLS_RSA_PUBLIC. * * \note Alternative implementations of RSA need not support - * mode being set to MBEDTLS_RSA_PRIVATE and may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * * \note The output buffer must be as large as the size - * of ctx->N (eg. 128 bytes if RSA-1024 is used). + * of ctx->N. For example, 128 Bytes if RSA-1024 is used. */ int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -609,39 +639,42 @@ int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx, unsigned char *output ); /** - * \brief Generic wrapper to perform a PKCS#1 decryption using the - * mode from the context. Do an RSA operation, then remove - * the message padding + * \brief This function performs an RSA operation, then removes the + * message padding. * - * \param ctx RSA context - * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE) - * \param p_rng RNG parameter - * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE - * \param olen will contain the plaintext length - * \param input buffer holding the encrypted data - * \param output buffer that will hold the plaintext - * \param output_max_len maximum length of the output buffer + * It is the generic wrapper for performing a PKCS#1 decryption + * operation using the \p mode from the context. + * + * \param ctx The RSA context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param olen The length of the plaintext. + * \param input The buffer holding the encrypted data. + * \param output The buffer used to hold the plaintext. + * \param output_max_len The maximum length of the output buffer. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PRIVATE. + * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library + * are likely to remove the \p mode argument and have it + * implicitly set to #MBEDTLS_RSA_PRIVATE. * * \note Alternative implementations of RSA need not support - * mode being set to MBEDTLS_RSA_PUBLIC and may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * * \note The output buffer length \c output_max_len should be - * as large as the size \c ctx->len of \c ctx->N (eg. 128 bytes - * if RSA-1024 is used) to be able to hold an arbitrary - * decrypted message. If it is not large enough to hold - * the decryption of the particular ciphertext provided, - * the function will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. + * as large as the size \p ctx->len of \p ctx->N (for example, + * 128 Bytes if RSA-1024 is used) to be able to hold an + * arbitrary decrypted message. If it is not large enough to + * hold the decryption of the particular ciphertext provided, + * the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. * * \note The input buffer must be as large as the size - * of \c ctx->N (eg. 128 bytes if RSA-1024 is used). + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. */ int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -652,37 +685,39 @@ int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, size_t output_max_len ); /** - * \brief Perform a PKCS#1 v1.5 decryption (RSAES-PKCS1-v1_5-DECRYPT) + * \brief This function performs a PKCS#1 v1.5 decryption + * operation (RSAES-PKCS1-v1_5-DECRYPT). * - * \param ctx RSA context - * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE) - * \param p_rng RNG parameter - * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE - * \param olen will contain the plaintext length - * \param input buffer holding the encrypted data - * \param output buffer that will hold the plaintext - * \param output_max_len maximum length of the output buffer + * \param ctx The RSA context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param olen The length of the plaintext. + * \param input The buffer holding the encrypted data. + * \param output The buffer to hold the plaintext. + * \param output_max_len The maximum length of the output buffer. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PRIVATE. + * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library + * are likely to remove the \p mode argument and have it + * implicitly set to #MBEDTLS_RSA_PRIVATE. * * \note Alternative implementations of RSA need not support - * mode being set to MBEDTLS_RSA_PUBLIC and may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * * \note The output buffer length \c output_max_len should be - * as large as the size \c ctx->len of \c ctx->N (eg. 128 bytes - * if RSA-1024 is used) to be able to hold an arbitrary - * decrypted message. If it is not large enough to hold - * the decryption of the particular ciphertext provided, - * the function will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. + * as large as the size \p ctx->len of \p ctx->N, for example, + * 128 Bytes if RSA-1024 is used, to be able to hold an + * arbitrary decrypted message. If it is not large enough to + * hold the decryption of the particular ciphertext provided, + * the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. * * \note The input buffer must be as large as the size - * of \c ctx->N (eg. 128 bytes if RSA-1024 is used). + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. */ int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -693,40 +728,42 @@ int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx, size_t output_max_len ); /** - * \brief Perform a PKCS#1 v2.1 OAEP decryption (RSAES-OAEP-DECRYPT) + * \brief This function performs a PKCS#1 v2.1 OAEP decryption + * operation (RSAES-OAEP-DECRYPT). * - * \param ctx RSA context - * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE) - * \param p_rng RNG parameter - * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE - * \param label buffer holding the custom label to use - * \param label_len contains the label length - * \param olen will contain the plaintext length - * \param input buffer holding the encrypted data - * \param output buffer that will hold the plaintext - * \param output_max_len maximum length of the output buffer + * \param ctx The RSA context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param label The buffer holding the custom label to use. + * \param label_len The length of the label. + * \param olen The length of the plaintext. + * \param input The buffer holding the encrypted data. + * \param output The buffer to hold the plaintext. + * \param output_max_len The maximum length of the output buffer. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PRIVATE. + * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library + * are likely to remove the \p mode argument and have it + * implicitly set to #MBEDTLS_RSA_PRIVATE. * * \note Alternative implementations of RSA need not support - * mode being set to MBEDTLS_RSA_PUBLIC and may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * * \note The output buffer length \c output_max_len should be - * as large as the size \c ctx->len of \c ctx->N (eg. 128 bytes - * if RSA-1024 is used) to be able to hold an arbitrary - * decrypted message. If it is not large enough to hold - * the decryption of the particular ciphertext provided, - * the function will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. + * as large as the size \p ctx->len of \p ctx->N, for + * example, 128 Bytes if RSA-1024 is used, to be able to + * hold an arbitrary decrypted message. If it is not + * large enough to hold the decryption of the particular + * ciphertext provided, the function returns + * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. * * \note The input buffer must be as large as the size - * of \c ctx->N (eg. 128 bytes if RSA-1024 is used). - * + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. */ int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -739,39 +776,41 @@ int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx, size_t output_max_len ); /** - * \brief Generic wrapper to perform a PKCS#1 signature using the - * mode from the context. Do a private RSA operation to sign - * a message digest + * \brief This function performs a private RSA operation to sign + * a message digest using PKCS#1. * - * \param ctx RSA context - * \param f_rng RNG function (Needed for PKCS#1 v2.1 encoding and for - * \c MBEDTLS_RSA_PRIVATE) - * \param p_rng RNG parameter - * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE - * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for - * signing raw data) - * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only) - * \param hash buffer holding the message digest - * \param sig buffer that will hold the ciphertext + * It is the generic wrapper for performing a PKCS#1 + * signature using the \p mode from the context. + * + * \param ctx The RSA context. + * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for + * #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param md_alg The message-digest algorithm used to hash the original data. + * Use #MBEDTLS_MD_NONE for signing raw data. + * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \param sig The buffer to hold the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PRIVATE. + * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library + * are likely to remove the \p mode argument and have it + * implicitly set to #MBEDTLS_RSA_PRIVATE. * * \note Alternative implementations of RSA need not support - * mode being set to MBEDTLS_RSA_PUBLIC and may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if the signing operation was successful, - * or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 if the signing operation was successful, + * or an \c MBEDTLS_ERR_RSA_XXX error code on failure. * - * \note The \c sig buffer must be as large as the size - * of \c ctx->N (eg. 128 bytes if RSA-1024 is used). + * \note The \p sig buffer must be as large as the size + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * - * \note In case of PKCS#1 v2.1 encoding, see comments on - * \c mbedtls_rsa_rsassa_pss_sign() for details on - * \c md_alg and \c hash_id. + * \note For PKCS#1 v2.1 encoding, see comments on + * mbedtls_rsa_rsassa_pss_sign() for details on + * \p md_alg and \p hash_id. */ int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -783,32 +822,34 @@ int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx, unsigned char *sig ); /** - * \brief Perform a PKCS#1 v1.5 signature (RSASSA-PKCS1-v1_5-SIGN) + * \brief This function performs a PKCS#1 v1.5 signature + * operation (RSASSA-PKCS1-v1_5-SIGN). * - * \param ctx RSA context - * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE) - * \param p_rng RNG parameter - * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE - * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE - * for signing raw data) - * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only) - * \param hash buffer holding the message digest - * \param sig buffer that will hold the ciphertext + * \param ctx The RSA context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param md_alg The message-digest algorithm used to hash the original data. + * Use #MBEDTLS_MD_NONE for signing raw data. + * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \param sig The buffer to hold the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PRIVATE. + * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library + * are likely to remove the \p mode argument and have it + * implicitly set to #MBEDTLS_RSA_PRIVATE. * * \note Alternative implementations of RSA need not support - * mode being set to MBEDTLS_RSA_PUBLIC and may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if the signing operation was successful, + * \return \c 0 if the signing operation was successful, * or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \note The \c sig buffer must be as large as the size - * of \c ctx->N (eg. 128 bytes if RSA-1024 is used). + * \note The \p sig buffer must be as large as the size + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. */ int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -820,38 +861,42 @@ int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx, unsigned char *sig ); /** - * \brief Perform a PKCS#1 v2.1 PSS signature (RSASSA-PSS-SIGN) + * \brief This function performs a PKCS#1 v2.1 PSS signature + * operation (RSASSA-PSS-SIGN). * - * \param ctx RSA context - * \param f_rng RNG function (Needed for PKCS#1 v2.1 encoding and for - * \c MBEDTLS_RSA_PRIVATE) - * \param p_rng RNG parameter - * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE - * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE - * for signing raw data) - * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only) - * \param hash buffer holding the message digest - * \param sig buffer that will hold the ciphertext + * \param ctx The RSA context. + * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for + * #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param md_alg The message-digest algorithm used to hash the original data. + * Use #MBEDTLS_MD_NONE for signing raw data. + * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \param sig The buffer to hold the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PRIVATE. + * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library + * are likely to remove the \p mode argument and have it + * implicitly set to #MBEDTLS_RSA_PRIVATE. * * \note Alternative implementations of RSA need not support - * mode being set to MBEDTLS_RSA_PUBLIC and may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if the signing operation was successful, + * \return \c 0 if the signing operation was successful, * or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \note The \c sig buffer must be as large as the size - * of \c ctx->N (eg. 128 bytes if RSA-1024 is used). + * \note The \p sig buffer must be as large as the size + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * - * \note The \c hash_id in the RSA context is the one used for the - * encoding. \c md_alg in the function call is the type of hash - * that is encoded. According to RFC 3447 it is advised to - * keep both hashes the same. + * \note The \p hash_id in the RSA context is the one used for the + * encoding. \p md_alg in the function call is the type of hash + * that is encoded. According to RFC-3447: Public-Key + * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography + * Specifications it is advised to keep both hashes the + * same. */ int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -863,36 +908,41 @@ int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx, unsigned char *sig ); /** - * \brief Generic wrapper to perform a PKCS#1 verification using the - * mode from the context. Do a public RSA operation and check - * the message digest + * \brief This function performs a public RSA operation and checks + * the message digest. * - * \param ctx points to an RSA public key - * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE) - * \param p_rng RNG parameter - * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE - * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data) - * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only) - * \param hash buffer holding the message digest - * \param sig buffer holding the ciphertext + * This is the generic wrapper for performing a PKCS#1 + * verification using the mode from the context. + * + * \param ctx The RSA public key context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param md_alg The message-digest algorithm used to hash the original data. + * Use #MBEDTLS_MD_NONE for signing raw data. + * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \param sig The buffer holding the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PUBLIC. + * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library + * are likely to remove the \p mode argument and have it + * set to #MBEDTLS_RSA_PUBLIC. * * \note Alternative implementations of RSA need not support - * mode being set to MBEDTLS_RSA_PRIVATE and may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if the verify operation was successful, + * \return \c 0 if the verify operation was successful, * or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \note The \c sig buffer must be as large as the size - * of \c ctx->N (eg. 128 bytes if RSA-1024 is used). + * \note The \p sig buffer must be as large as the size + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * - * \note In case of PKCS#1 v2.1 encoding, see comments on - * \c mbedtls_rsa_rsassa_pss_verify() about md_alg and hash_id. + * \note For PKCS#1 v2.1 encoding, see comments on + * mbedtls_rsa_rsassa_pss_verify() about \p md_alg and + * \p hash_id. */ int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -904,32 +954,34 @@ int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx, const unsigned char *sig ); /** - * \brief Perform a PKCS#1 v1.5 verification (RSASSA-PKCS1-v1_5-VERIFY) + * \brief This function performs a PKCS#1 v1.5 verification + * operation (RSASSA-PKCS1-v1_5-VERIFY). * - * \param ctx points to an RSA public key - * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE) - * \param p_rng RNG parameter - * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE - * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE - * for signing raw data) - * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only) - * \param hash buffer holding the message digest - * \param sig buffer holding the ciphertext + * \param ctx The RSA public key context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param md_alg The message-digest algorithm used to hash the original data. + * Use #MBEDTLS_MD_NONE for signing raw data. + * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \param sig The buffer holding the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PUBLIC. + * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library + * are likely to remove the \p mode argument and have it + * set to #MBEDTLS_RSA_PUBLIC. * * \note Alternative implementations of RSA need not support - * mode being set to MBEDTLS_RSA_PRIVATE and may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if the verify operation was successful, + * \return \c 0 if the verify operation was successful, * or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \note The \c sig buffer must be as large as the size - * of \c ctx->N (eg. 128 bytes if RSA-1024 is used). + * \note The \p sig buffer must be as large as the size + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. */ int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -941,38 +993,45 @@ int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx, const unsigned char *sig ); /** - * \brief Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY) - * (This is the "simple" version.) + * \brief This function performs a PKCS#1 v2.1 PSS verification + * operation (RSASSA-PSS-VERIFY). * - * \param ctx points to an RSA public key - * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE) - * \param p_rng RNG parameter - * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE - * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data) - * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only) - * \param hash buffer holding the message digest - * \param sig buffer holding the ciphertext + * The hash function for the MGF mask generating function + * is that specified in the RSA context. + * + * \param ctx The RSA public key context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param md_alg The message-digest algorithm used to hash the original data. + * Use #MBEDTLS_MD_NONE for signing raw data. + * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \param sig The buffer holding the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PUBLIC. + * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library + * are likely to remove the \p mode argument and have it + * implicitly set to #MBEDTLS_RSA_PUBLIC. * * \note Alternative implementations of RSA need not support - * mode being set to MBEDTLS_RSA_PRIVATE and may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if the verify operation was successful, + * \return \c 0 if the verify operation was successful, * or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \note The \c sig buffer must be as large as the size - * of \c ctx->N (eg. 128 bytes if RSA-1024 is used). + * \note The \p sig buffer must be as large as the size + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * - * \note The \c hash_id in the RSA context is the one used for the - * verification. \c md_alg in the function call is the type of - * hash that is verified. According to RFC 3447 it is advised to - * keep both hashes the same. If \c hash_id in the RSA context is - * unset, the \c md_alg from the function call is used. + * \note The \p hash_id in the RSA context is the one used for the + * verification. \p md_alg in the function call is the type of + * hash that is verified. According to RFC-3447: Public-Key + * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography + * Specifications it is advised to keep both hashes the + * same. If \p hash_id in the RSA context is unset, + * the \p md_alg from the function call is used. */ int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -984,28 +1043,33 @@ int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx, const unsigned char *sig ); /** - * \brief Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY) - * (This is the version with "full" options.) + * \brief This function performs a PKCS#1 v2.1 PSS verification + * operation (RSASSA-PSS-VERIFY). * - * \param ctx points to an RSA public key - * \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE) - * \param p_rng RNG parameter - * \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE - * \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data) - * \param hashlen message digest length (for \c MBEDTLS_MD_NONE only) - * \param hash buffer holding the message digest - * \param mgf1_hash_id message digest used for mask generation - * \param expected_salt_len Length of the salt used in padding, use - * \c MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length - * \param sig buffer holding the ciphertext + * The hash function for the MGF mask generating function + * is that specified in \p mgf1_hash_id. * - * \return 0 if the verify operation was successful, + * \param ctx The RSA public key context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param md_alg The message-digest algorithm used to hash the original data. + * Use #MBEDTLS_MD_NONE for signing raw data. + * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \param mgf1_hash_id The message digest used for mask generation. + * \param expected_salt_len The length of the salt used in padding. Use + * #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length. + * \param sig The buffer holding the ciphertext. + * + * \return \c 0 if the verify operation was successful, * or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \note The \c sig buffer must be as large as the size - * of \c ctx->N (eg. 128 bytes if RSA-1024 is used). + * \note The \p sig buffer must be as large as the size + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * - * \note The \c hash_id in the RSA context is ignored. + * \note The \p hash_id in the RSA context is ignored. */ int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -1019,20 +1083,20 @@ int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx, const unsigned char *sig ); /** - * \brief Copy the components of an RSA context + * \brief This function copies the components of an RSA context. * - * \param dst Destination context - * \param src Source context + * \param dst The destination context. + * \param src The source context. * - * \return 0 on success, - * \c MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure + * \return \c 0 on success, + * #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure. */ int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src ); /** - * \brief Free the components of an RSA key + * \brief This function frees the components of an RSA key. * - * \param ctx RSA Context to free + * \param ctx The RSA Context to free. */ void mbedtls_rsa_free( mbedtls_rsa_context *ctx ); @@ -1049,9 +1113,9 @@ extern "C" { #endif /** - * \brief Checkup routine + * \brief The RSA checkup routine. * - * \return 0 if successful, or 1 if the test failed + * \return \c 0 on success, or \c 1 on failure. */ int mbedtls_rsa_self_test( int verbose ); diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h index 4d3a164018..700a348315 100644 --- a/include/mbedtls/sha1.h +++ b/include/mbedtls/sha1.h @@ -1,10 +1,10 @@ /** * \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 * * 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 * 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 #define MBEDTLS_SHA1_H @@ -49,68 +49,70 @@ extern "C" { #endif /** - * \brief SHA-1 context structure + * \brief The SHA-1 context structure. */ typedef struct { - uint32_t total[2]; /*!< number of bytes processed */ - uint32_t state[5]; /*!< intermediate digest state */ - unsigned char buffer[64]; /*!< data block being processed */ + uint32_t total[2]; /*!< The number of Bytes processed. */ + uint32_t state[5]; /*!< The intermediate digest state. */ + unsigned char buffer[64]; /*!< The data block being processed. */ } 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 ); /** - * \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 ); /** - * \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 src The context to be cloned + * \param dst The destination context. + * \param src The context to clone. */ void mbedtls_sha1_clone( mbedtls_sha1_context *dst, 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 ); /** - * \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 input buffer holding the data - * \param ilen length of the input data + * \param ctx The SHA-1 context. + * \param input The buffer holding 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, const unsigned char *input, 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 output SHA-1 checksum result + * \param ctx The SHA-1 context. + * \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, 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) * * \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, 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 * - * \param ctx context to be initialized + * \param ctx The SHA-1 context to be initialized. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_starts( 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 * - * \param ctx SHA-1 context - * \param input buffer holding the data - * \param ilen length of the input data + * \param ctx The SHA-1 context. + * \param input The buffer holding the input data. + * \param ilen The length of the input data. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_update( 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 * - * \param ctx SHA-1 context - * \param output SHA-1 checksum result + * \param ctx The SHA-1 context. + * \param output The SHA-1 checksum result. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_finish( 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 * - * \param ctx SHA-1 context - * \param data buffer holding one block of data + * \param ctx The SHA-1 context. + * \param data The data block being processed. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1_process( mbedtls_sha1_context *ctx, @@ -208,13 +210,19 @@ extern "C" { #endif /** - * \brief Output = SHA-1( input buffer ) + * \brief This function calculates the SHA-1 checksum of a buffer. * - * \param input buffer holding the data - * \param ilen length of the input data - * \param output SHA-1 checksum result + * The function allocates the context, performs the + * calculation, and frees the context. * - * \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, 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 * - * \param input buffer holding the data - * \param ilen length of the input data - * \param output SHA-1 checksum result + * \param input The buffer holding the input data. + * \param ilen The length of the input data. + * \param output The SHA-1 checksum result. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha1( const unsigned char *input, size_t ilen, @@ -246,9 +254,9 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha1( const unsigned char *input, #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 ); diff --git a/include/mbedtls/sha256.h b/include/mbedtls/sha256.h index 5c5d07ad2b..a2b6e11644 100644 --- a/include/mbedtls/sha256.h +++ b/include/mbedtls/sha256.h @@ -1,10 +1,10 @@ /** * \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 * * 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 * 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 #define MBEDTLS_SHA256_H @@ -39,7 +39,6 @@ !defined(inline) && !defined(__cplusplus) #define inline __inline #endif - #if !defined(MBEDTLS_SHA256_ALT) // Regular implementation // @@ -49,81 +48,94 @@ extern "C" { #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 { - uint32_t total[2]; /*!< number of bytes processed */ - uint32_t state[8]; /*!< intermediate digest state */ - unsigned char buffer[64]; /*!< data block being processed */ - int is224; /*!< 0 => SHA-256, else SHA-224 */ + uint32_t total[2]; /*!< The number of Bytes processed. */ + uint32_t state[8]; /*!< The intermediate digest state. */ + unsigned char buffer[64]; /*!< The data block being processed. */ + int is224; /*!< Determines which function to use. +
  • 0: Use SHA-256.
    • +
  • 1: Use SHA-224.
*/ } 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 ); /** - * \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 ); /** - * \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 src The context to be cloned + * \param dst The destination context. + * \param src The context to clone. */ void mbedtls_sha256_clone( mbedtls_sha256_context *dst, 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 is224 0 = use SHA256, 1 = use SHA224 + * \param ctx The context to initialize. + * \param is224 Determines which function to use. + *
  • 0: Use SHA-256.
    • + *
  • 1: Use SHA-224.
* - * \return 0 if successful + * \return \c 0 on success. */ 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 input buffer holding the 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, const unsigned char *input, 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 output SHA-224/256 checksum result + * \param ctx The SHA-256 context. + * \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, 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 data buffer holding one block of data + * \param ctx The SHA-256 context. + * \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, const unsigned char data[64] ); @@ -135,12 +147,14 @@ int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx, #define MBEDTLS_DEPRECATED #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 is224 0 = use SHA256, 1 = use SHA224 + * \param ctx The SHA-256 context to initialize. + * \param is224 Determines which function to use. + *
  • 0: Use SHA-256.
    • + *
  • 1: Use SHA-224.
*/ MBEDTLS_DEPRECATED static inline void mbedtls_sha256_starts( 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 input buffer holding the data - * \param ilen length of the input data + * \param ctx The SHA-256 context to initialize. + * \param input The buffer holding the data. + * \param ilen The length of the input data. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha256_update( 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 output SHA-224/256 checksum result + * \param ctx The SHA-256 context. + * \param output The SHA-224or SHA-256 checksum result. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha256_finish( 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 data buffer holding one block of data + * \param ctx The SHA-256 context. + * \param data The buffer holding one block of data. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha256_process( mbedtls_sha256_context *ctx, @@ -198,7 +216,6 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha256_process( #undef MBEDTLS_DEPRECATED #endif /* !MBEDTLS_DEPRECATED_REMOVED */ - #ifdef __cplusplus } #endif @@ -212,14 +229,21 @@ extern "C" { #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 - * \param ilen length of the input data - * \param output SHA-224/256 checksum result - * \param is224 0 = use SHA256, 1 = use SHA224 + * The function allocates the context, performs the + * calculation, and frees the context. * - * \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. + *
  • 0: Use SHA-256.
    • + *
  • 1: Use SHA-224.
*/ int mbedtls_sha256_ret( const unsigned char *input, size_t ilen, @@ -232,15 +256,25 @@ int mbedtls_sha256_ret( const unsigned char *input, #else #define MBEDTLS_DEPRECATED #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 - * \param ilen length of the input data - * \param output SHA-224/256 checksum result - * \param is224 0 = use SHA256, 1 = use SHA224 + * The SHA-256 result is calculated as + * output = SHA-256(input buffer). + * + * \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. + *
  • 0: Use SHA-256.
    • + *
  • 1: Use SHA-224.
*/ MBEDTLS_DEPRECATED static inline void mbedtls_sha256( const unsigned char *input, @@ -255,9 +289,9 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha256( #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 ); diff --git a/include/mbedtls/sha512.h b/include/mbedtls/sha512.h index 7453c44d4d..52ae204d44 100644 --- a/include/mbedtls/sha512.h +++ b/include/mbedtls/sha512.h @@ -1,10 +1,10 @@ /** * \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 * * 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 * 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 #define MBEDTLS_SHA512_H @@ -39,7 +39,6 @@ !defined(inline) && !defined(__cplusplus) #define inline __inline #endif - #if !defined(MBEDTLS_SHA512_ALT) // Regular implementation // @@ -49,85 +48,97 @@ extern "C" { #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 { - uint64_t total[2]; /*!< number of bytes processed */ - uint64_t state[8]; /*!< intermediate digest state */ - unsigned char buffer[128]; /*!< data block being processed */ - int is384; /*!< 0 => SHA-512, else SHA-384 */ + uint64_t total[2]; /*!< The number of Bytes processed. */ + uint64_t state[8]; /*!< The intermediate digest state. */ + unsigned char buffer[128]; /*!< The data block being processed. */ + int is384; /*!< Determines which function to use. + *
  • 0: Use SHA-512.
    • + *
  • 1: Use SHA-384.
*/ } 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 ); /** - * \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 ); /** - * \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 src The context to be cloned + * \param dst The destination context. + * \param src The context to clone. */ void mbedtls_sha512_clone( mbedtls_sha512_context *dst, 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 is384 0 = use SHA512, 1 = use SHA384 + * \param ctx The SHA-512 context to initialize. + * \param is384 Determines which function to use. + *
  • 0: Use SHA-512.
    • + *
  • 1: Use SHA-384.
* - * \return 0 if successful + * \return \c 0 on success. */ 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 input buffer holding the data - * \param ilen length of the input data + * \param ctx The SHA-512 context. + * \param input The buffer holding 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, - const unsigned char *input, - size_t ilen ); + const unsigned char *input, + 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 output SHA-384/512 checksum result + * \param ctx The SHA-512 context. + * \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, 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 data buffer holding one block of data + * \param ctx The SHA-512 context. + * \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, const unsigned char data[128] ); - #if !defined(MBEDTLS_DEPRECATED_REMOVED) #if defined(MBEDTLS_DEPRECATED_WARNING) #define MBEDTLS_DEPRECATED __attribute__((deprecated)) @@ -135,12 +146,15 @@ int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx, #define MBEDTLS_DEPRECATED #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 * - * \param ctx context to be initialized - * \param is384 0 = use SHA512, 1 = use SHA384 + * \param ctx The SHA-512 context to initialize. + * \param is384 Determines which function to use. + *
  • 0: Use SHA-512.
    • + *
  • 1: Use SHA-384.
*/ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_starts( 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 * - * \param ctx SHA-512 context - * \param input buffer holding the data - * \param ilen length of the input data + * \param ctx The SHA-512 context. + * \param input The buffer holding the data. + * \param ilen The length of the input data. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_update( 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 * - * \param ctx SHA-512 context - * \param output SHA-384/512 checksum result + * \param ctx The SHA-512 context. + * \param output The SHA-384 or SHA-512 checksum result. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_finish( 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 * - * \param ctx SHA-512 context - * \param data buffer holding one block of data + * \param ctx The SHA-512 context. + * \param data The buffer holding one block of data. */ MBEDTLS_DEPRECATED static inline void mbedtls_sha512_process( mbedtls_sha512_context *ctx, @@ -212,14 +230,23 @@ extern "C" { #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 - * \param ilen length of the input data - * \param output SHA-384/512 checksum result - * \param is384 0 = use SHA512, 1 = use SHA384 + * The function allocates the context, performs the + * calculation, and frees the context. * - * \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. + *
  • 0: Use SHA-512.
    • + *
  • 1: Use SHA-384.
+ * + * \return \c 0 on success. */ int mbedtls_sha512_ret( const unsigned char *input, size_t ilen, @@ -233,14 +260,23 @@ int mbedtls_sha512_ret( const unsigned char *input, #define MBEDTLS_DEPRECATED #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 * - * \param input buffer holding the data - * \param ilen length of the input data - * \param output SHA-384/512 checksum result - * \param is384 0 = use SHA512, 1 = use SHA384 + * \param input The buffer holding the 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. + *
  • 0: Use SHA-512.
    • + *
  • 1: Use SHA-384.
*/ MBEDTLS_DEPRECATED static inline void mbedtls_sha512( const unsigned char *input, @@ -253,11 +289,10 @@ MBEDTLS_DEPRECATED static inline void mbedtls_sha512( #undef MBEDTLS_DEPRECATED #endif /* !MBEDTLS_DEPRECATED_REMOVED */ - -/** - * \brief Checkup routine + /** + * \brief The SHA-384 or SHA-512 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 ); diff --git a/library/error.c b/library/error.c index 42bcde6b99..0292480aee 100644 --- a/library/error.c +++ b/library/error.c @@ -210,7 +210,7 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen ) if( use_ret == -(MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE) ) mbedtls_snprintf( buf, buflen, "CIPHER - The selected feature is not available" ); 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) ) mbedtls_snprintf( buf, buflen, "CIPHER - Failed to allocate memory" ); 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) ) mbedtls_snprintf( buf, buflen, "CIPHER - Authentication failed (for AEAD modes)" ); 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) ) mbedtls_snprintf( buf, buflen, "CIPHER - Cipher hardware accelerator failed" ); #endif /* MBEDTLS_CIPHER_C */ #if defined(MBEDTLS_DHM_C) 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) ) mbedtls_snprintf( buf, buflen, "DHM - Reading of the DHM parameters 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) ) mbedtls_snprintf( buf, buflen, "DHM - Allocation of memory failed" ); 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) ) mbedtls_snprintf( buf, buflen, "DHM - DHM hardware accelerator 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) ) mbedtls_snprintf( buf, buflen, "RSA - Something failed during generation of a key" ); 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) ) mbedtls_snprintf( buf, buflen, "RSA - The public key operation 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) ) mbedtls_snprintf( buf, buflen, "RSA - The random generator failed to generate non-zeros" ); 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) ) mbedtls_snprintf( buf, buflen, "RSA - RSA hardware accelerator failed" ); #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) ) mbedtls_snprintf( buf, buflen, "AES - Invalid data input length" ); 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) ) mbedtls_snprintf( buf, buflen, "AES - AES hardware accelerator failed" ); #endif /* MBEDTLS_AES_C */ @@ -644,7 +644,7 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen ) #if defined(MBEDTLS_CCM_C) 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) ) mbedtls_snprintf( buf, buflen, "CCM - Authenticated decryption 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) ) mbedtls_snprintf( buf, buflen, "CTR_DRBG - The entropy source failed" ); 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) ) - 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) ) - 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 */ #if defined(MBEDTLS_DES_C)