sdk/include/reactos/libs/mbedtls/ccm.h

   1 /**
   2  * \file ccm.h
   3  *
   4  * \brief CCM combines Counter mode encryption with CBC-MAC authentication
   5  *        for 128-bit block ciphers.
   6  *
   7  * Input to CCM includes the following elements:
   8  * <ul><li>Payload - data that is both authenticated and encrypted.</li>
   9  * <li>Associated data (Adata) - data that is authenticated but not
  10  * encrypted, For example, a header.</li>
  11  * <li>Nonce - A unique value that is assigned to the payload and the
  12  * associated data.</li></ul>
  13  *
  14  */
  15 /*
  16  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  17  *  SPDX-License-Identifier: GPL-2.0
  18  *
  19  *  This program is free software; you can redistribute it and/or modify
  20  *  it under the terms of the GNU General Public License as published by
  21  *  the Free Software Foundation; either version 2 of the License, or
  22  *  (at your option) any later version.
  23  *
  24  *  This program is distributed in the hope that it will be useful,
  25  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  26  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  27  *  GNU General Public License for more details.
  28  *
  29  *  You should have received a copy of the GNU General Public License along
  30  *  with this program; if not, write to the Free Software Foundation, Inc.,
  31  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  32  *
  33  *  This file is part of Mbed TLS (https://tls.mbed.org)
  34  */
  35
  36 #ifndef MBEDTLS_CCM_H
  37 #define MBEDTLS_CCM_H
  38
  39 #if !defined(MBEDTLS_CONFIG_FILE)
  40 #include "config.h"
  41 #else
  42 #include MBEDTLS_CONFIG_FILE
  43 #endif
  44
  45 #include "cipher.h"
  46
  47 #define MBEDTLS_ERR_CCM_BAD_INPUT       -0x000D /**< Bad input parameters to the function. */
  48 #define MBEDTLS_ERR_CCM_AUTH_FAILED     -0x000F /**< Authenticated decryption failed. */
  49 #define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */
  50
  51 #if !defined(MBEDTLS_CCM_ALT)
  52 // Regular implementation
  53 //
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58
  59 /**
  60  * \brief    The CCM context-type definition. The CCM context is passed
  61  *           to the APIs called.
  62  */
  63 typedef struct {
  64     mbedtls_cipher_context_t cipher_ctx;    /*!< The cipher context used. */
  65 }
  66 mbedtls_ccm_context;
  67
  68 /**
  69  * \brief           This function initializes the specified CCM context,
  70  *                  to make references valid, and prepare the context
  71  *                  for mbedtls_ccm_setkey() or mbedtls_ccm_free().
  72  *
  73  * \param ctx       The CCM context to initialize.
  74  */
  75 void mbedtls_ccm_init( mbedtls_ccm_context *ctx );
  76
  77 /**
  78  * \brief           This function initializes the CCM context set in the
  79  *                  \p ctx parameter and sets the encryption key.
  80  *
  81  * \param ctx       The CCM context to initialize.
  82  * \param cipher    The 128-bit block cipher to use.
  83  * \param key       The encryption key.
  84  * \param keybits   The key size in bits. This must be acceptable by the cipher.
  85  *
  86  * \return          \c 0 on success, or a cipher-specific error code.
  87  */
  88 int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx,
  89                         mbedtls_cipher_id_t cipher,
  90                         const unsigned char *key,
  91                         unsigned int keybits );
  92
  93 /**
  94  * \brief   This function releases and clears the specified CCM context
  95  *          and underlying cipher sub-context.
  96  *
  97  * \param ctx       The CCM context to clear.
  98  */
  99 void mbedtls_ccm_free( mbedtls_ccm_context *ctx );
 100
 101 /**
 102  * \brief           This function encrypts a buffer using CCM.
 103  *
 104  * \param ctx       The CCM context to use for encryption.
 105  * \param length    The length of the input data in Bytes.
 106  * \param iv        Initialization vector (nonce).
 107  * \param iv_len    The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
 108  * \param add       The additional data field.
 109  * \param add_len   The length of additional data in Bytes.
 110  *                  Must be less than 2^16 - 2^8.
 111  * \param input     The buffer holding the input data.
 112  * \param output    The buffer holding the output data.
 113  *                  Must be at least \p length Bytes wide.
 114  * \param tag       The buffer holding the tag.
 115  * \param tag_len   The length of the tag to generate in Bytes:
 116  *                  4, 6, 8, 10, 12, 14 or 16.
 117  *
 118  * \note            The tag is written to a separate buffer. To concatenate
 119  *                  the \p tag with the \p output, as done in <em>RFC-3610:
 120  *                  Counter with CBC-MAC (CCM)</em>, use
 121  *                  \p tag = \p output + \p length, and make sure that the
 122  *                  output buffer is at least \p length + \p tag_len wide.
 123  *
 124  * \return          \c 0 on success.
 125  */
 126 int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length,
 127                          const unsigned char *iv, size_t iv_len,
 128                          const unsigned char *add, size_t add_len,
 129                          const unsigned char *input, unsigned char *output,
 130                          unsigned char *tag, size_t tag_len );
 131
 132 /**
 133  * \brief           This function performs a CCM authenticated decryption of a
 134  *                  buffer.
 135  *
 136  * \param ctx       The CCM context to use for decryption.
 137  * \param length    The length of the input data in Bytes.
 138  * \param iv        Initialization vector.
 139  * \param iv_len    The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
 140  * \param add       The additional data field.
 141  * \param add_len   The length of additional data in Bytes.
 142  *                  Must be less than 2^16 - 2^8.
 143  * \param input     The buffer holding the input data.
 144  * \param output    The buffer holding the output data.
 145  *                  Must be at least \p length Bytes wide.
 146  * \param tag       The buffer holding the tag.
 147  * \param tag_len   The length of the tag in Bytes.
 148  *                  4, 6, 8, 10, 12, 14 or 16.
 149  *
 150  * \return          0 if successful and authenticated, or
 151  *                  #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
 152  */
 153 int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length,
 154                       const unsigned char *iv, size_t iv_len,
 155                       const unsigned char *add, size_t add_len,
 156                       const unsigned char *input, unsigned char *output,
 157                       const unsigned char *tag, size_t tag_len );
 158
 159 #ifdef __cplusplus
 160 }
 161 #endif
 162
 163 #else  /* MBEDTLS_CCM_ALT */
 164 #include "ccm_alt.h"
 165 #endif /* MBEDTLS_CCM_ALT */
 166
 167 #ifdef __cplusplus
 168 extern "C" {
 169 #endif
 170
 171 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
 172 /**
 173  * \brief          The CCM checkup routine.
 174  *
 175  * \return         \c 0 on success, or \c 1 on failure.
 176  */
 177 int mbedtls_ccm_self_test( int verbose );
 178 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
 179
 180 #ifdef __cplusplus
 181 }
 182 #endif
 183
 184 #endif /* MBEDTLS_CCM_H */