mirror of
https://github.com/yuzu-emu/mbedtls.git
synced 2024-11-30 06:44:14 +01:00
a3974435ea
Now that descriptions of error codes no longer have to be on the same line for the sake of generate_errors.pl, move them to their own line before the definition. This aligns them with what we do for other definitions, and means that we no longer need to have very long lines containing both the C definition and the comment. ``` perl -i -pe 's~^(#define +MBEDTLS_ERR_\w+ +-\w+) */\*[*!]<(.*)\*/~/**$2*/\n$1~' include/mbedtls/*.h ``` This commit does not change the output of generate_errors.pl. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
312 lines
14 KiB
C
312 lines
14 KiB
C
/**
|
|
* \file ccm.h
|
|
*
|
|
* \brief This file provides an API for the CCM authenticated encryption
|
|
* mode for block ciphers.
|
|
*
|
|
* 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 The Mbed TLS Contributors
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
* not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
#ifndef MBEDTLS_CCM_H
|
|
#define MBEDTLS_CCM_H
|
|
|
|
#if !defined(MBEDTLS_CONFIG_FILE)
|
|
#include "mbedtls/config.h"
|
|
#else
|
|
#include MBEDTLS_CONFIG_FILE
|
|
#endif
|
|
|
|
#include "mbedtls/cipher.h"
|
|
|
|
/** Bad input parameters to the function. */
|
|
#define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D
|
|
/** Authenticated decryption failed. */
|
|
#define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F
|
|
|
|
/* MBEDTLS_ERR_CCM_HW_ACCEL_FAILED is deprecated and should not be used. */
|
|
/** CCM hardware accelerator failed. */
|
|
#define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#if !defined(MBEDTLS_CCM_ALT)
|
|
// Regular implementation
|
|
//
|
|
|
|
/**
|
|
* \brief The CCM context-type definition. The CCM context is passed
|
|
* to the APIs called.
|
|
*/
|
|
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 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 The CCM context to initialize. This must not be \c NULL.
|
|
*/
|
|
void mbedtls_ccm_init( mbedtls_ccm_context *ctx );
|
|
|
|
/**
|
|
* \brief This function initializes the CCM context set in the
|
|
* \p ctx parameter and sets the encryption key.
|
|
*
|
|
* \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 \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,
|
|
const unsigned char *key,
|
|
unsigned int keybits );
|
|
|
|
/**
|
|
* \brief This function releases and clears the specified CCM context
|
|
* and underlying cipher sub-context.
|
|
*
|
|
* \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 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
|
|
* writable 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,
|
|
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 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
|
|
* writable 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 *add, size_t add_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 The CCM checkup routine.
|
|
*
|
|
* \return \c 0 on success.
|
|
* \return \c 1 on failure.
|
|
*/
|
|
int mbedtls_ccm_self_test( int verbose );
|
|
#endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* MBEDTLS_CCM_H */
|