cuberite/polarssl
1
0
Fork 0
mirror of https://github.com/cuberite/polarssl.git synced 2025-10-30 03:00:21 -04:00
Code Issues Packages Projects Releases Wiki Activity

Improve CCM documentation

Browse Source 
- Rephrase function/parameter/enum/define/error descriptions into full and
  clear sentences.
- Make sure to adhering to the Arm writing guidelines.
- Fix missing/incorrect Doxygen tags.
- Standardize terminology used within the file.
- Fix iv_len values per the standard.

GitHub PR: #1305
This commit is contained in:
Rose Zadik 2018-01-24 12:56:53 +00:00 committed by Jaeden Amero
parent 7f44127c71
commit eecdbea30f
2 changed files with 72 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
include/mbedtls/ccm.h
View File

@ -1,10 +1,19 @@
/** /**
* \file ccm.h * \file ccm.h
* *
* \brief Counter with CBC-MAC (CCM) for 128-bit block ciphers * \brief CCM combines Counter mode encryption with CBC-MAC authentication
* for 128-bit block ciphers.
*
* Input to CCM includes the following elements:
* <ul><li>Payload - data that is both authenticated and encrypted.</li>
* <li>Associated data (Adata) - data that is authenticated but not
* encrypted, For example, a header.</li>
* <li>Nonce - A unique value that is assigned to the payload and the
* associated data.</li></ul>
*
*/ */
/* /*
* Copyright (C) 2006-2015, ARM Limited, All Rights Reserved * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
* SPDX-License-Identifier: Apache-2.0 * SPDX-License-Identifier: Apache-2.0
* *
* Licensed under the Apache License, Version 2.0 (the "License"); you may * Licensed under the Apache License, Version 2.0 (the "License"); you may
@ -19,16 +28,17 @@
* See the License for the specific language governing permissions and * See the License for the specific language governing permissions and
* limitations under the License. * limitations under the License.
* *
* This file is part of mbed TLS (https://tls.mbed.org) * This file is part of Mbed TLS (https://tls.mbed.org)
*/ */
#ifndef MBEDTLS_CCM_H #ifndef MBEDTLS_CCM_H
#define MBEDTLS_CCM_H #define MBEDTLS_CCM_H
#include "cipher.h" #include "cipher.h"
#define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D /**< Bad input parameters to function. */ #define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D /**< Bad input parameters to the function. */
#define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F /**< Authenticated decryption failed. */ #define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F /**< Authenticated decryption failed. */
#define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */ #define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */
#if !defined(MBEDTLS_CCM_ALT) #if !defined(MBEDTLS_CCM_ALT)
// Regular implementation // Regular implementation
@ -39,31 +49,33 @@ extern "C" {
#endif #endif
/** /**
* \brief CCM context structure * \brief The CCM context-type definition. The CCM context is passed
* to the APIs called.
*/ */
typedef struct { typedef struct {
mbedtls_cipher_context_t cipher_ctx; /*!< cipher context used */ mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */
} }
mbedtls_ccm_context; mbedtls_ccm_context;
/** /**
* \brief Initialize CCM context (just makes references valid) * \brief This function initializes the specified CCM context,
* Makes the context ready for mbedtls_ccm_setkey() or * to make references valid, and prepare the context
* mbedtls_ccm_free(). * for mbedtls_ccm_setkey() or mbedtls_ccm_free().
* *
* \param ctx CCM context to initialize * \param ctx The CCM context to initialize.
*/ */
void mbedtls_ccm_init( mbedtls_ccm_context *ctx ); void mbedtls_ccm_init( mbedtls_ccm_context *ctx );
/** /**
* \brief CCM initialization (encryption and decryption) * \brief This function initializes the CCM context set in the
* \p ctx parameter and sets the encryption key.
* *
* \param ctx CCM context to be initialized * \param ctx The CCM context to initialize.
* \param cipher cipher to use (a 128-bit block cipher) * \param cipher The 128-bit block cipher to use.
* \param key encryption key * \param key The encryption key.
* \param keybits key size in bits (must be acceptable by the cipher) * \param keybits The key size in bits. This must be acceptable by the cipher.
* *
* \return 0 if successful, or a cipher specific error code * \return \c 0 on success, or a cipher-specific error code.
*/ */
int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx, int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx,
mbedtls_cipher_id_t cipher, mbedtls_cipher_id_t cipher,
@ -71,36 +83,37 @@ int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx,
unsigned int keybits ); unsigned int keybits );
/** /**
* \brief Free a CCM context and underlying cipher sub-context * \brief This function releases and clears the specified CCM context
* and underlying cipher sub-context.
* *
* \param ctx CCM context to free * \param ctx The CCM context to clear.
*/ */
void mbedtls_ccm_free( mbedtls_ccm_context *ctx ); void mbedtls_ccm_free( mbedtls_ccm_context *ctx );
/** /**
* \brief CCM buffer encryption * \brief This function encrypts a buffer using CCM.
* *
* \param ctx CCM context * \param ctx The CCM context to use for encryption.
* \param length length of the input data in bytes * \param length The length of the input data in Bytes.
* \param iv nonce (initialization vector) * \param iv Initialization vector (nonce).
* \param iv_len length of IV in bytes * \param iv_len The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
* must be 2, 3, 4, 5, 6, 7 or 8 * \param add The additional data field.
* \param add additional data * \param add_len The length of additional data in Bytes.
* \param add_len length of additional data in bytes * Must be less than 2^16 - 2^8.
* must be less than 2^16 - 2^8 * \param input The buffer holding the input data.
* \param input buffer holding the input data * \param output The buffer holding the output data.
* \param output buffer for holding the output data * Must be at least \p length Bytes wide.
* must be at least 'length' bytes wide * \param tag The buffer holding the tag.
* \param tag buffer for holding the tag * \param tag_len The length of the tag to generate in Bytes:
* \param tag_len length of the tag to generate in bytes * 4, 6, 8, 10, 14 or 16.
* must be 4, 6, 8, 10, 14 or 16
* *
* \note The tag is written to a separate buffer. To get the tag * \note The tag is written to a separate buffer. To concatenate
* concatenated with the output as in the CCM spec, use * the \p tag with the \p output, as done in <em>RFC-3610:
* tag = output + length and make sure the output buffer is * Counter with CBC-MAC (CCM)</em>, use
* at least length + tag_len wide. * \p tag = \p output + \p length, and make sure that the
* output buffer is at least \p length + \p tag_len wide.
* *
* \return 0 if successful * \return \c 0 on success.
*/ */
int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
const unsigned char *iv, size_t iv_len, const unsigned char *iv, size_t iv_len,
@ -109,21 +122,22 @@ int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
unsigned char *tag, size_t tag_len ); unsigned char *tag, size_t tag_len );
/** /**
* \brief CCM buffer authenticated decryption * \brief This function performs a CCM authenticated decryption of a
* buffer.
* *
* \param ctx CCM context * \param ctx The CCM context to use for decryption.
* \param length length of the input data * \param length The length of the input data in Bytes.
* \param iv initialization vector * \param iv Initialization vector.
* \param iv_len length of IV * \param iv_len The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
* \param add additional data * \param add The additional data field.
* \param add_len length of additional data * \param add_len The length of additional data in Bytes.
* \param input buffer holding the input data * \param input The buffer holding the input data.
* \param output buffer for holding the output data * \param output The buffer holding the output data.
* \param tag buffer holding the tag * \param tag The buffer holding the tag.
* \param tag_len length of the tag * \param tag_len The length of the tag in Bytes.
* *
* \return 0 if successful and authenticated, * \return 0 if successful and authenticated, or
* MBEDTLS_ERR_CCM_AUTH_FAILED if tag does not match * #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
*/ */
int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
const unsigned char *iv, size_t iv_len, const unsigned char *iv, size_t iv_len,
@ -135,9 +149,9 @@ int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
} }
#endif #endif
#else /* !MBEDTLS_CCM_ALT */ #else /* MBEDTLS_CCM_ALT */
#include "ccm_alt.h" #include "ccm_alt.h"
#endif /* !MBEDTLS_CCM_ALT */ #endif /* MBEDTLS_CCM_ALT */
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
@ -145,9 +159,9 @@ extern "C" {
#if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C) #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
/** /**
* \brief Checkup routine * \brief The CCM checkup routine.
* *
* \return 0 if successful, or 1 if the test failed * \return \c 0 on success, or \c 1 on failure.
*/ */
int mbedtls_ccm_self_test( int verbose ); int mbedtls_ccm_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */ #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */

2
library/error.c
View File

@ -642,7 +642,7 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen )
#if defined(MBEDTLS_CCM_C) #if defined(MBEDTLS_CCM_C)
if( use_ret == -(MBEDTLS_ERR_CCM_BAD_INPUT) ) if( use_ret == -(MBEDTLS_ERR_CCM_BAD_INPUT) )
mbedtls_snprintf( buf, buflen, "CCM - Bad input parameters to function" ); mbedtls_snprintf( buf, buflen, "CCM - Bad input parameters to the function" );
if( use_ret == -(MBEDTLS_ERR_CCM_AUTH_FAILED) ) if( use_ret == -(MBEDTLS_ERR_CCM_AUTH_FAILED) )
mbedtls_snprintf( buf, buflen, "CCM - Authenticated decryption failed" ); mbedtls_snprintf( buf, buflen, "CCM - Authenticated decryption failed" );
if( use_ret == -(MBEDTLS_ERR_CCM_HW_ACCEL_FAILED) ) if( use_ret == -(MBEDTLS_ERR_CCM_HW_ACCEL_FAILED) )