1 /** 2 * \file ccm.h 3 * 4 * \brief This file provides an API for the CCM authenticated encryption 5 * mode for block ciphers. 6 * 7 * CCM combines Counter mode encryption with CBC-MAC authentication 8 * for 128-bit block ciphers. 9 * 10 * Input to CCM includes the following elements: 11 * <ul><li>Payload - data that is both authenticated and encrypted.</li> 12 * <li>Associated data (Adata) - data that is authenticated but not 13 * encrypted, For example, a header.</li> 14 * <li>Nonce - A unique value that is assigned to the payload and the 15 * associated data.</li></ul> 16 * 17 * Definition of CCM: 18 * http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf 19 * RFC 3610 "Counter with CBC-MAC (CCM)" 20 * 21 * Related: 22 * RFC 5116 "An Interface and Algorithms for Authenticated Encryption" 23 * 24 * Definition of CCM*: 25 * IEEE 802.15.4 - IEEE Standard for Local and metropolitan area networks 26 * Integer representation is fixed most-significant-octet-first order and 27 * the representation of octets is most-significant-bit-first order. This is 28 * consistent with RFC 3610. 29 */ 30 /* 31 * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved 32 * SPDX-License-Identifier: Apache-2.0 33 * 34 * Licensed under the Apache License, Version 2.0 (the "License"); you may 35 * not use this file except in compliance with the License. 36 * You may obtain a copy of the License at 37 * 38 * http://www.apache.org/licenses/LICENSE-2.0 39 * 40 * Unless required by applicable law or agreed to in writing, software 41 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 42 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 43 * See the License for the specific language governing permissions and 44 * limitations under the License. 45 * 46 * This file is part of Mbed TLS (https://tls.mbed.org) 47 */ 48 49 #ifndef MBEDTLS_CCM_H 50 #define MBEDTLS_CCM_H 51 52 #include "cipher.h" 53 54 #define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D /**< Bad input parameters to the function. */ 55 #define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F /**< Authenticated decryption failed. */ 56 57 /* MBEDTLS_ERR_CCM_HW_ACCEL_FAILED is deprecated and should not be used. */ 58 #define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 /**< CCM hardware accelerator failed. */ 59 60 #ifdef __cplusplus 61 extern "C" { 62 #endif 63 64 #if !defined(MBEDTLS_CCM_ALT) 65 // Regular implementation 66 // 67 68 /** 69 * \brief The CCM context-type definition. The CCM context is passed 70 * to the APIs called. 71 */ 72 typedef struct mbedtls_ccm_context 73 { 74 mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */ 75 } 76 mbedtls_ccm_context; 77 78 #else /* MBEDTLS_CCM_ALT */ 79 #include "ccm_alt.h" 80 #endif /* MBEDTLS_CCM_ALT */ 81 82 /** 83 * \brief This function initializes the specified CCM context, 84 * to make references valid, and prepare the context 85 * for mbedtls_ccm_setkey() or mbedtls_ccm_free(). 86 * 87 * \param ctx The CCM context to initialize. This must not be \c NULL. 88 */ 89 void mbedtls_ccm_init( mbedtls_ccm_context *ctx ); 90 91 /** 92 * \brief This function initializes the CCM context set in the 93 * \p ctx parameter and sets the encryption key. 94 * 95 * \param ctx The CCM context to initialize. This must be an initialized 96 * context. 97 * \param cipher The 128-bit block cipher to use. 98 * \param key The encryption key. This must not be \c NULL. 99 * \param keybits The key size in bits. This must be acceptable by the cipher. 100 * 101 * \return \c 0 on success. 102 * \return A CCM or cipher-specific error code on failure. 103 */ 104 int mbedtls_ccm_setkey( mbedtls_ccm_context *ctx, 105 mbedtls_cipher_id_t cipher, 106 const unsigned char *key, 107 unsigned int keybits ); 108 109 /** 110 * \brief This function releases and clears the specified CCM context 111 * and underlying cipher sub-context. 112 * 113 * \param ctx The CCM context to clear. If this is \c NULL, the function 114 * has no effect. Otherwise, this must be initialized. 115 */ 116 void mbedtls_ccm_free( mbedtls_ccm_context *ctx ); 117 118 /** 119 * \brief This function encrypts a buffer using CCM. 120 * 121 * \note The tag is written to a separate buffer. To concatenate 122 * the \p tag with the \p output, as done in <em>RFC-3610: 123 * Counter with CBC-MAC (CCM)</em>, use 124 * \p tag = \p output + \p length, and make sure that the 125 * output buffer is at least \p length + \p tag_len wide. 126 * 127 * \param ctx The CCM context to use for encryption. This must be 128 * initialized and bound to a key. 129 * \param length The length of the input data in Bytes. 130 * \param iv The initialization vector (nonce). This must be a readable 131 * buffer of at least \p iv_len Bytes. 132 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 133 * or 13. The length L of the message length field is 134 * 15 - \p iv_len. 135 * \param add The additional data field. If \p add_len is greater than 136 * zero, \p add must be a readable buffer of at least that 137 * length. 138 * \param add_len The length of additional data in Bytes. 139 * This must be less than `2^16 - 2^8`. 140 * \param input The buffer holding the input data. If \p length is greater 141 * than zero, \p input must be a readable buffer of at least 142 * that length. 143 * \param output The buffer holding the output data. If \p length is greater 144 * than zero, \p output must be a writable buffer of at least 145 * that length. 146 * \param tag The buffer holding the authentication field. This must be a 147 * readable buffer of at least \p tag_len Bytes. 148 * \param tag_len The length of the authentication field to generate in Bytes: 149 * 4, 6, 8, 10, 12, 14 or 16. 150 * 151 * \return \c 0 on success. 152 * \return A CCM or cipher-specific error code on failure. 153 */ 154 int mbedtls_ccm_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, 155 const unsigned char *iv, size_t iv_len, 156 const unsigned char *add, size_t add_len, 157 const unsigned char *input, unsigned char *output, 158 unsigned char *tag, size_t tag_len ); 159 160 /** 161 * \brief This function encrypts a buffer using CCM*. 162 * 163 * \note The tag is written to a separate buffer. To concatenate 164 * the \p tag with the \p output, as done in <em>RFC-3610: 165 * Counter with CBC-MAC (CCM)</em>, use 166 * \p tag = \p output + \p length, and make sure that the 167 * output buffer is at least \p length + \p tag_len wide. 168 * 169 * \note When using this function in a variable tag length context, 170 * the tag length has to be encoded into the \p iv passed to 171 * this function. 172 * 173 * \param ctx The CCM context to use for encryption. This must be 174 * initialized and bound to a key. 175 * \param length The length of the input data in Bytes. 176 * \param iv The initialization vector (nonce). This must be a readable 177 * buffer of at least \p iv_len Bytes. 178 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 179 * or 13. The length L of the message length field is 180 * 15 - \p iv_len. 181 * \param add The additional data field. This must be a readable buffer of 182 * at least \p add_len Bytes. 183 * \param add_len The length of additional data in Bytes. 184 * This must be less than 2^16 - 2^8. 185 * \param input The buffer holding the input data. If \p length is greater 186 * than zero, \p input must be a readable buffer of at least 187 * that length. 188 * \param output The buffer holding the output data. If \p length is greater 189 * than zero, \p output must be a writable buffer of at least 190 * that length. 191 * \param tag The buffer holding the authentication field. This must be a 192 * readable buffer of at least \p tag_len Bytes. 193 * \param tag_len The length of the authentication field to generate in Bytes: 194 * 0, 4, 6, 8, 10, 12, 14 or 16. 195 * 196 * \warning Passing \c 0 as \p tag_len means that the message is no 197 * longer authenticated. 198 * 199 * \return \c 0 on success. 200 * \return A CCM or cipher-specific error code on failure. 201 */ 202 int mbedtls_ccm_star_encrypt_and_tag( mbedtls_ccm_context *ctx, size_t length, 203 const unsigned char *iv, size_t iv_len, 204 const unsigned char *add, size_t add_len, 205 const unsigned char *input, unsigned char *output, 206 unsigned char *tag, size_t tag_len ); 207 208 /** 209 * \brief This function performs a CCM authenticated decryption of a 210 * buffer. 211 * 212 * \param ctx The CCM context to use for decryption. This must be 213 * initialized and bound to a key. 214 * \param length The length of the input data in Bytes. 215 * \param iv The initialization vector (nonce). This must be a readable 216 * buffer of at least \p iv_len Bytes. 217 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 218 * or 13. The length L of the message length field is 219 * 15 - \p iv_len. 220 * \param add The additional data field. This must be a readable buffer 221 * of at least that \p add_len Bytes.. 222 * \param add_len The length of additional data in Bytes. 223 * This must be less than 2^16 - 2^8. 224 * \param input The buffer holding the input data. If \p length is greater 225 * than zero, \p input must be a readable buffer of at least 226 * that length. 227 * \param output The buffer holding the output data. If \p length is greater 228 * than zero, \p output must be a writable buffer of at least 229 * that length. 230 * \param tag The buffer holding the authentication field. This must be a 231 * readable buffer of at least \p tag_len Bytes. 232 * \param tag_len The length of the authentication field to generate in Bytes: 233 * 4, 6, 8, 10, 12, 14 or 16. 234 * 235 * \return \c 0 on success. This indicates that the message is authentic. 236 * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. 237 * \return A cipher-specific error code on calculation failure. 238 */ 239 int mbedtls_ccm_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, 240 const unsigned char *iv, size_t iv_len, 241 const unsigned char *add, size_t add_len, 242 const unsigned char *input, unsigned char *output, 243 const unsigned char *tag, size_t tag_len ); 244 245 /** 246 * \brief This function performs a CCM* authenticated decryption of a 247 * buffer. 248 * 249 * \note When using this function in a variable tag length context, 250 * the tag length has to be decoded from \p iv and passed to 251 * this function as \p tag_len. (\p tag needs to be adjusted 252 * accordingly.) 253 * 254 * \param ctx The CCM context to use for decryption. This must be 255 * initialized and bound to a key. 256 * \param length The length of the input data in Bytes. 257 * \param iv The initialization vector (nonce). This must be a readable 258 * buffer of at least \p iv_len Bytes. 259 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 260 * or 13. The length L of the message length field is 261 * 15 - \p iv_len. 262 * \param add The additional data field. This must be a readable buffer of 263 * at least that \p add_len Bytes. 264 * \param add_len The length of additional data in Bytes. 265 * This must be less than 2^16 - 2^8. 266 * \param input The buffer holding the input data. If \p length is greater 267 * than zero, \p input must be a readable buffer of at least 268 * that length. 269 * \param output The buffer holding the output data. If \p length is greater 270 * than zero, \p output must be a writable buffer of at least 271 * that length. 272 * \param tag The buffer holding the authentication field. This must be a 273 * readable buffer of at least \p tag_len Bytes. 274 * \param tag_len The length of the authentication field in Bytes. 275 * 0, 4, 6, 8, 10, 12, 14 or 16. 276 * 277 * \warning Passing \c 0 as \p tag_len means that the message is nos 278 * longer authenticated. 279 * 280 * \return \c 0 on success. 281 * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. 282 * \return A cipher-specific error code on calculation failure. 283 */ 284 int mbedtls_ccm_star_auth_decrypt( mbedtls_ccm_context *ctx, size_t length, 285 const unsigned char *iv, size_t iv_len, 286 const unsigned char *add, size_t add_len, 287 const unsigned char *input, unsigned char *output, 288 const unsigned char *tag, size_t tag_len ); 289 290 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C) 291 /** 292 * \brief The CCM checkup routine. 293 * 294 * \return \c 0 on success. 295 * \return \c 1 on failure. 296 */ 297 int mbedtls_ccm_self_test( int verbose ); 298 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */ 299 300 #ifdef __cplusplus 301 } 302 #endif 303 304 #endif /* MBEDTLS_CCM_H */ 305