/**
* \file ccm.h
*
- * \brief Counter with CBC-MAC (CCM) for 128-bit block ciphers
+ * \brief This file provides an API for the CCM authenticated encryption
+ * mode for block ciphers.
*
- * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ * 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>
+ *
+ * Definition of CCM:
+ * http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf
+ * RFC 3610 "Counter with CBC-MAC (CCM)"
+ *
+ * Related:
+ * RFC 5116 "An Interface and Algorithms for Authenticated Encryption"
+ *
+ * Definition of CCM*:
+ * IEEE 802.15.4 - IEEE Standard for Local and metropolitan area networks
+ * Integer representation is fixed most-significant-octet-first order and
+ * the representation of octets is most-significant-bit-first order. This is
+ * consistent with RFC 3610.
+ */
+/*
+ * 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
* 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
+#if !defined(MBEDTLS_CONFIG_FILE)
+#include "config.h"
+#else
+#include MBEDTLS_CONFIG_FILE
+#endif
+
#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_BAD_INPUT -0x000D /**< Bad input parameters to the function. */
+#define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F /**< Authenticated decryption failed. */
+
+/* MBEDTLS_ERR_CCM_HW_ACCEL_FAILED is deprecated and should not be used. */
+#define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */
#ifdef __cplusplus
extern "C" {
#endif
+#if !defined(MBEDTLS_CCM_ALT)
+// Regular implementation
+//
+
/**
- * \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 */
+typedef struct mbedtls_ccm_context
+{
+ mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */
}
mbedtls_ccm_context;
+#else /* MBEDTLS_CCM_ALT */
+#include "ccm_alt.h"
+#endif /* MBEDTLS_CCM_ALT */
+
/**
- * \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. This must not be \c NULL.
*/
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. This must be an initialized
+ * context.
+ * \param cipher The 128-bit block cipher to use.
+ * \param key The encryption key. This must not be \c NULL.
+ * \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.
+ * \return A CCM or cipher-specific error code on failure.
*/
int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx,
mbedtls_cipher_id_t cipher,
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. If this is \c NULL, the function
+ * has no effect. Otherwise, this must be initialized.
*/
void mbedtls_ccm_free( mbedtls_ccm_context *ctx );
/**
- * \brief CCM buffer encryption
- *
- * \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
- *
- * \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.
- *
- * \return 0 if successful
+ * \brief This function encrypts a buffer using CCM.
+ *
+ * \note The tag is written to a separate buffer. To concatenate
+ * the \p tag with the \p output, as done in <em>RFC-3610:
+ * Counter with CBC-MAC (CCM)</em>, use
+ * \p tag = \p output + \p length, and make sure that the
+ * output buffer is at least \p length + \p tag_len wide.
+ *
+ * \param ctx The CCM context to use for encryption. This must be
+ * initialized and bound to a key.
+ * \param length The length of the input data in Bytes.
+ * \param iv The initialization vector (nonce). This must be a readable
+ * buffer of at least \p iv_len Bytes.
+ * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
+ * or 13. The length L of the message length field is
+ * 15 - \p iv_len.
+ * \param add The additional data field. If \p add_len is greater than
+ * zero, \p add must be a readable buffer of at least that
+ * length.
+ * \param add_len The length of additional data in Bytes.
+ * This must be less than `2^16 - 2^8`.
+ * \param input The buffer holding the input data. If \p length is greater
+ * than zero, \p input must be a readable buffer of at least
+ * that length.
+ * \param output The buffer holding the output data. If \p length is greater
+ * than zero, \p output must be a writable buffer of at least
+ * that length.
+ * \param tag The buffer holding the authentication field. This must be a
+ * readable buffer of at least \p tag_len Bytes.
+ * \param tag_len The length of the authentication field to generate in Bytes:
+ * 4, 6, 8, 10, 12, 14 or 16.
+ *
+ * \return \c 0 on success.
+ * \return A CCM or cipher-specific error code on failure.
*/
int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
const unsigned char *iv, size_t iv_len,
unsigned char *tag, size_t tag_len );
/**
- * \brief CCM buffer authenticated decryption
- *
- * \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
- *
- * \return 0 if successful and authenticated,
- * MBEDTLS_ERR_CCM_AUTH_FAILED if tag does not match
+ * \brief This function encrypts a buffer using CCM*.
+ *
+ * \note The tag is written to a separate buffer. To concatenate
+ * the \p tag with the \p output, as done in <em>RFC-3610:
+ * Counter with CBC-MAC (CCM)</em>, use
+ * \p tag = \p output + \p length, and make sure that the
+ * output buffer is at least \p length + \p tag_len wide.
+ *
+ * \note When using this function in a variable tag length context,
+ * the tag length has to be encoded into the \p iv passed to
+ * this function.
+ *
+ * \param ctx The CCM context to use for encryption. This must be
+ * initialized and bound to a key.
+ * \param length The length of the input data in Bytes.
+ * \param iv The initialization vector (nonce). This must be a readable
+ * buffer of at least \p iv_len Bytes.
+ * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
+ * or 13. The length L of the message length field is
+ * 15 - \p iv_len.
+ * \param add The additional data field. This must be a readable buffer of
+ * at least \p add_len Bytes.
+ * \param add_len The length of additional data in Bytes.
+ * This must be less than 2^16 - 2^8.
+ * \param input The buffer holding the input data. If \p length is greater
+ * than zero, \p input must be a readable buffer of at least
+ * that length.
+ * \param output The buffer holding the output data. If \p length is greater
+ * than zero, \p output must be a writable buffer of at least
+ * that length.
+ * \param tag The buffer holding the authentication field. This must be a
+ * readable buffer of at least \p tag_len Bytes.
+ * \param tag_len The length of the authentication field to generate in Bytes:
+ * 0, 4, 6, 8, 10, 12, 14 or 16.
+ *
+ * \warning Passing \c 0 as \p tag_len means that the message is no
+ * longer authenticated.
+ *
+ * \return \c 0 on success.
+ * \return A CCM or cipher-specific error code on failure.
+ */
+int mbedtls_ccm_star_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
+ const unsigned char *iv, size_t iv_len,
+ const unsigned char *add, size_t add_len,
+ const unsigned char *input, unsigned char *output,
+ unsigned char *tag, size_t tag_len );
+
+/**
+ * \brief This function performs a CCM authenticated decryption of a
+ * buffer.
+ *
+ * \param ctx The CCM context to use for decryption. This must be
+ * initialized and bound to a key.
+ * \param length The length of the input data in Bytes.
+ * \param iv The initialization vector (nonce). This must be a readable
+ * buffer of at least \p iv_len Bytes.
+ * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
+ * or 13. The length L of the message length field is
+ * 15 - \p iv_len.
+ * \param add The additional data field. This must be a readable buffer
+ * of at least that \p add_len Bytes..
+ * \param add_len The length of additional data in Bytes.
+ * This must be less than 2^16 - 2^8.
+ * \param input The buffer holding the input data. If \p length is greater
+ * than zero, \p input must be a readable buffer of at least
+ * that length.
+ * \param output The buffer holding the output data. If \p length is greater
+ * than zero, \p output must be a writable buffer of at least
+ * that length.
+ * \param tag The buffer holding the authentication field. This must be a
+ * readable buffer of at least \p tag_len Bytes.
+ * \param tag_len The length of the authentication field to generate in Bytes:
+ * 4, 6, 8, 10, 12, 14 or 16.
+ *
+ * \return \c 0 on success. This indicates that the message is authentic.
+ * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
+ * \return A cipher-specific error code on calculation failure.
*/
int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
const unsigned char *iv, size_t iv_len,
const unsigned char *input, unsigned char *output,
const unsigned char *tag, size_t tag_len );
+/**
+ * \brief This function performs a CCM* authenticated decryption of a
+ * buffer.
+ *
+ * \note When using this function in a variable tag length context,
+ * the tag length has to be decoded from \p iv and passed to
+ * this function as \p tag_len. (\p tag needs to be adjusted
+ * accordingly.)
+ *
+ * \param ctx The CCM context to use for decryption. This must be
+ * initialized and bound to a key.
+ * \param length The length of the input data in Bytes.
+ * \param iv The initialization vector (nonce). This must be a readable
+ * buffer of at least \p iv_len Bytes.
+ * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
+ * or 13. The length L of the message length field is
+ * 15 - \p iv_len.
+ * \param add The additional data field. This must be a readable buffer of
+ * at least that \p add_len Bytes.
+ * \param add_len The length of additional data in Bytes.
+ * This must be less than 2^16 - 2^8.
+ * \param input The buffer holding the input data. If \p length is greater
+ * than zero, \p input must be a readable buffer of at least
+ * that length.
+ * \param output The buffer holding the output data. If \p length is greater
+ * than zero, \p output must be a writable buffer of at least
+ * that length.
+ * \param tag The buffer holding the authentication field. This must be a
+ * readable buffer of at least \p tag_len Bytes.
+ * \param tag_len The length of the authentication field in Bytes.
+ * 0, 4, 6, 8, 10, 12, 14 or 16.
+ *
+ * \warning Passing \c 0 as \p tag_len means that the message is nos
+ * longer authenticated.
+ *
+ * \return \c 0 on success.
+ * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
+ * \return A cipher-specific error code on calculation failure.
+ */
+int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
+ const unsigned char *iv, size_t iv_len,
+ const unsigned char *add, size_t add_len,
+ const unsigned char *input, unsigned char *output,
+ const unsigned char *tag, size_t tag_len );
+
#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.
+ * \return \c 1 on failure.
*/
int mbedtls_ccm_self_test( int verbose );
#endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
projects / platform / upstream / iotivity.git / blobdiff