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 The Mbed TLS Contributors 32 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 33 */ 34 35 #ifndef MBEDTLS_CCM_H 36 #define MBEDTLS_CCM_H 37 38 #if !defined(MBEDTLS_CONFIG_FILE) 39 #include "mbedtls/config.h" 40 #else 41 #include MBEDTLS_CONFIG_FILE 42 #endif 43 44 #include "mbedtls/cipher.h" 45 46 /** Bad input parameters to the function. */ 47 #define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D 48 /** Authenticated decryption failed. */ 49 #define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F 50 51 /* MBEDTLS_ERR_CCM_HW_ACCEL_FAILED is deprecated and should not be used. */ 52 /** CCM hardware accelerator failed. */ 53 #define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011 54 55 #ifdef __cplusplus 56 extern "C" { 57 #endif 58 59 #if !defined(MBEDTLS_CCM_ALT) 60 // Regular implementation 61 // 62 63 /** 64 * \brief The CCM context-type definition. The CCM context is passed 65 * to the APIs called. 66 */ 67 typedef struct mbedtls_ccm_context { 68 mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */ 69 } 70 mbedtls_ccm_context; 71 72 #else /* MBEDTLS_CCM_ALT */ 73 #include "ccm_alt.h" 74 #endif /* MBEDTLS_CCM_ALT */ 75 76 /** 77 * \brief This function initializes the specified CCM context, 78 * to make references valid, and prepare the context 79 * for mbedtls_ccm_setkey() or mbedtls_ccm_free(). 80 * 81 * \param ctx The CCM context to initialize. This must not be \c NULL. 82 */ 83 void mbedtls_ccm_init(mbedtls_ccm_context *ctx); 84 85 /** 86 * \brief This function initializes the CCM context set in the 87 * \p ctx parameter and sets the encryption key. 88 * 89 * \param ctx The CCM context to initialize. This must be an initialized 90 * context. 91 * \param cipher The 128-bit block cipher to use. 92 * \param key The encryption key. This must not be \c NULL. 93 * \param keybits The key size in bits. This must be acceptable by the cipher. 94 * 95 * \return \c 0 on success. 96 * \return A CCM or cipher-specific error code on failure. 97 */ 98 int mbedtls_ccm_setkey(mbedtls_ccm_context *ctx, 99 mbedtls_cipher_id_t cipher, 100 const unsigned char *key, 101 unsigned int keybits); 102 103 /** 104 * \brief This function releases and clears the specified CCM context 105 * and underlying cipher sub-context. 106 * 107 * \param ctx The CCM context to clear. If this is \c NULL, the function 108 * has no effect. Otherwise, this must be initialized. 109 */ 110 void mbedtls_ccm_free(mbedtls_ccm_context *ctx); 111 112 /** 113 * \brief This function encrypts a buffer using CCM. 114 * 115 * \note The tag is written to a separate buffer. To concatenate 116 * the \p tag with the \p output, as done in <em>RFC-3610: 117 * Counter with CBC-MAC (CCM)</em>, use 118 * \p tag = \p output + \p length, and make sure that the 119 * output buffer is at least \p length + \p tag_len wide. 120 * 121 * \param ctx The CCM context to use for encryption. This must be 122 * initialized and bound to a key. 123 * \param length The length of the input data in Bytes. 124 * \param iv The initialization vector (nonce). This must be a readable 125 * buffer of at least \p iv_len Bytes. 126 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 127 * or 13. The length L of the message length field is 128 * 15 - \p iv_len. 129 * \param add The additional data field. If \p add_len is greater than 130 * zero, \p add must be a readable buffer of at least that 131 * length. 132 * \param add_len The length of additional data in Bytes. 133 * This must be less than `2^16 - 2^8`. 134 * \param input The buffer holding the input data. If \p length is greater 135 * than zero, \p input must be a readable buffer of at least 136 * that length. 137 * \param output The buffer holding the output data. If \p length is greater 138 * than zero, \p output must be a writable buffer of at least 139 * that length. 140 * \param tag The buffer holding the authentication field. This must be a 141 * writable buffer of at least \p tag_len Bytes. 142 * \param tag_len The length of the authentication field to generate in Bytes: 143 * 4, 6, 8, 10, 12, 14 or 16. 144 * 145 * \return \c 0 on success. 146 * \return A CCM or cipher-specific error code on failure. 147 */ 148 int mbedtls_ccm_encrypt_and_tag(mbedtls_ccm_context *ctx, size_t length, 149 const unsigned char *iv, size_t iv_len, 150 const unsigned char *add, size_t add_len, 151 const unsigned char *input, unsigned char *output, 152 unsigned char *tag, size_t tag_len); 153 154 /** 155 * \brief This function encrypts a buffer using CCM*. 156 * 157 * \note The tag is written to a separate buffer. To concatenate 158 * the \p tag with the \p output, as done in <em>RFC-3610: 159 * Counter with CBC-MAC (CCM)</em>, use 160 * \p tag = \p output + \p length, and make sure that the 161 * output buffer is at least \p length + \p tag_len wide. 162 * 163 * \note When using this function in a variable tag length context, 164 * the tag length has to be encoded into the \p iv passed to 165 * this function. 166 * 167 * \param ctx The CCM context to use for encryption. This must be 168 * initialized and bound to a key. 169 * \param length The length of the input data in Bytes. 170 * \param iv The initialization vector (nonce). This must be a readable 171 * buffer of at least \p iv_len Bytes. 172 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 173 * or 13. The length L of the message length field is 174 * 15 - \p iv_len. 175 * \param add The additional data field. This must be a readable buffer of 176 * at least \p add_len Bytes. 177 * \param add_len The length of additional data in Bytes. 178 * This must be less than 2^16 - 2^8. 179 * \param input The buffer holding the input data. If \p length is greater 180 * than zero, \p input must be a readable buffer of at least 181 * that length. 182 * \param output The buffer holding the output data. If \p length is greater 183 * than zero, \p output must be a writable buffer of at least 184 * that length. 185 * \param tag The buffer holding the authentication field. This must be a 186 * writable buffer of at least \p tag_len Bytes. 187 * \param tag_len The length of the authentication field to generate in Bytes: 188 * 0, 4, 6, 8, 10, 12, 14 or 16. 189 * 190 * \warning Passing \c 0 as \p tag_len means that the message is no 191 * longer authenticated. 192 * 193 * \return \c 0 on success. 194 * \return A CCM or cipher-specific error code on failure. 195 */ 196 int mbedtls_ccm_star_encrypt_and_tag(mbedtls_ccm_context *ctx, size_t length, 197 const unsigned char *iv, size_t iv_len, 198 const unsigned char *add, size_t add_len, 199 const unsigned char *input, unsigned char *output, 200 unsigned char *tag, size_t tag_len); 201 202 /** 203 * \brief This function performs a CCM authenticated decryption of a 204 * buffer. 205 * 206 * \param ctx The CCM context to use for decryption. This must be 207 * initialized and bound to a key. 208 * \param length The length of the input data in Bytes. 209 * \param iv The initialization vector (nonce). This must be a readable 210 * buffer of at least \p iv_len Bytes. 211 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 212 * or 13. The length L of the message length field is 213 * 15 - \p iv_len. 214 * \param add The additional data field. This must be a readable buffer 215 * of at least that \p add_len Bytes.. 216 * \param add_len The length of additional data in Bytes. 217 * This must be less than 2^16 - 2^8. 218 * \param input The buffer holding the input data. If \p length is greater 219 * than zero, \p input must be a readable buffer of at least 220 * that length. 221 * \param output The buffer holding the output data. If \p length is greater 222 * than zero, \p output must be a writable buffer of at least 223 * that length. 224 * \param tag The buffer holding the authentication field. This must be a 225 * readable buffer of at least \p tag_len Bytes. 226 * \param tag_len The length of the authentication field to generate in Bytes: 227 * 4, 6, 8, 10, 12, 14 or 16. 228 * 229 * \return \c 0 on success. This indicates that the message is authentic. 230 * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. 231 * \return A cipher-specific error code on calculation failure. 232 */ 233 int mbedtls_ccm_auth_decrypt(mbedtls_ccm_context *ctx, size_t length, 234 const unsigned char *iv, size_t iv_len, 235 const unsigned char *add, size_t add_len, 236 const unsigned char *input, unsigned char *output, 237 const unsigned char *tag, size_t tag_len); 238 239 /** 240 * \brief This function performs a CCM* authenticated decryption of a 241 * buffer. 242 * 243 * \note When using this function in a variable tag length context, 244 * the tag length has to be decoded from \p iv and passed to 245 * this function as \p tag_len. (\p tag needs to be adjusted 246 * accordingly.) 247 * 248 * \param ctx The CCM context to use for decryption. This must be 249 * initialized and bound to a key. 250 * \param length The length of the input data in Bytes. 251 * \param iv The initialization vector (nonce). This must be a readable 252 * buffer of at least \p iv_len Bytes. 253 * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, 254 * or 13. The length L of the message length field is 255 * 15 - \p iv_len. 256 * \param add The additional data field. This must be a readable buffer of 257 * at least that \p add_len Bytes. 258 * \param add_len The length of additional data in Bytes. 259 * This must be less than 2^16 - 2^8. 260 * \param input The buffer holding the input data. If \p length is greater 261 * than zero, \p input must be a readable buffer of at least 262 * that length. 263 * \param output The buffer holding the output data. If \p length is greater 264 * than zero, \p output must be a writable buffer of at least 265 * that length. 266 * \param tag The buffer holding the authentication field. This must be a 267 * readable buffer of at least \p tag_len Bytes. 268 * \param tag_len The length of the authentication field in Bytes. 269 * 0, 4, 6, 8, 10, 12, 14 or 16. 270 * 271 * \warning Passing \c 0 as \p tag_len means that the message is nos 272 * longer authenticated. 273 * 274 * \return \c 0 on success. 275 * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match. 276 * \return A cipher-specific error code on calculation failure. 277 */ 278 int mbedtls_ccm_star_auth_decrypt(mbedtls_ccm_context *ctx, size_t length, 279 const unsigned char *iv, size_t iv_len, 280 const unsigned char *add, size_t add_len, 281 const unsigned char *input, unsigned char *output, 282 const unsigned char *tag, size_t tag_len); 283 284 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C) 285 /** 286 * \brief The CCM checkup routine. 287 * 288 * \return \c 0 on success. 289 * \return \c 1 on failure. 290 */ 291 int mbedtls_ccm_self_test(int verbose); 292 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */ 293 294 #ifdef __cplusplus 295 } 296 #endif 297 298 #endif /* MBEDTLS_CCM_H */ 299