1 /* Copyright (c) (2010-2012,2014-2023) Apple Inc. All rights reserved. 2 * 3 * corecrypto is licensed under Apple Inc.’s Internal Use License Agreement (which 4 * is contained in the License.txt file distributed with corecrypto) and only to 5 * people who accept that license. IMPORTANT: Any license rights granted to you by 6 * Apple Inc. (if any) are limited to internal use within your organization only on 7 * devices and computers you own or control, for the sole purpose of verifying the 8 * security characteristics and correct functioning of the Apple Software. You may 9 * not, directly or indirectly, redistribute the Apple Software or any portions thereof. 10 */ 11 12 #ifndef _CORECRYPTO_CCMODE_H_ 13 #define _CORECRYPTO_CCMODE_H_ 14 15 #include <corecrypto/cc_config.h> 16 #include <corecrypto/cc_priv.h> 17 #include <corecrypto/ccmode_impl.h> 18 #include <corecrypto/ccmode_siv.h> 19 #include <corecrypto/ccmode_siv_hmac.h> 20 21 CC_PTRCHECK_CAPABLE_HEADER() 22 23 /* ECB mode. */ 24 25 /* Declare a ecb key named _name_. Pass the size field of a struct ccmode_ecb 26 for _size_. */ 27 #define ccecb_ctx_decl(_size_, _name_) cc_ctx_decl_vla(ccecb_ctx, _size_, _name_) 28 #define ccecb_ctx_clear(_size_, _name_) cc_clear(_size_, _name_) 29 30 size_t ccecb_context_size(const struct ccmode_ecb *mode); 31 32 size_t ccecb_block_size(const struct ccmode_ecb *mode); 33 34 int ccecb_init(const struct ccmode_ecb *mode, ccecb_ctx *ctx, size_t key_len, const void *cc_sized_by(key_len) key); 35 36 int ccecb_update(const struct ccmode_ecb *mode, const ccecb_ctx *ctx, size_t nblocks, const void *cc_indexable in, void *cc_indexable out); 37 38 cc_ptrcheck_unavailable_r(ccecb_one_shot_explicit) 39 int ccecb_one_shot(const struct ccmode_ecb *mode, 40 size_t key_len, 41 const void *cc_sized_by(key_len) key, 42 size_t nblocks, 43 const void *cc_unsafe_indexable in, 44 void *cc_unsafe_indexable out); 45 46 int ccecb_one_shot_explicit(const struct ccmode_ecb *mode, 47 size_t key_len, 48 size_t block_size, 49 size_t nblocks, 50 const void *cc_sized_by(key_len) key, 51 const void *cc_sized_by(block_size * nblocks) in, 52 void *cc_sized_by(block_size * nblocks) out); 53 54 /* CBC mode. */ 55 56 /* Declare a cbc key named _name_. Pass the size field of a struct ccmode_cbc 57 for _size_. */ 58 #define cccbc_ctx_decl(_size_, _name_) cc_ctx_decl_vla(cccbc_ctx, _size_, _name_) 59 #define cccbc_ctx_clear(_size_, _name_) cc_clear(_size_, _name_) 60 61 /* Declare a cbc iv tweak named _name_. Pass the blocksize field of a 62 struct ccmode_cbc for _size_. */ 63 #define cccbc_iv_decl(_size_, _name_) cc_ctx_decl_vla(cccbc_iv, _size_, _name_) 64 #define cccbc_iv_clear(_size_, _name_) cc_clear(_size_, _name_) 65 66 /* Actual symmetric algorithm implementation can provide you one of these. 67 68 Alternatively you can create a ccmode_cbc instance from any ccmode_ecb 69 cipher. To do so, statically initialize a struct ccmode_cbc using the 70 CCMODE_FACTORY_CBC_DECRYPT or CCMODE_FACTORY_CBC_ENCRYPT macros. 71 Alternatively you can dynamically initialize a struct ccmode_cbc 72 ccmode_factory_cbc_decrypt() or ccmode_factory_cbc_encrypt(). */ 73 74 size_t cccbc_context_size(const struct ccmode_cbc *mode); 75 76 size_t cccbc_block_size(const struct ccmode_cbc *mode); 77 78 int cccbc_init(const struct ccmode_cbc *mode, cccbc_ctx *ctx, size_t key_len, const void *cc_sized_by(key_len) key); 79 80 int cccbc_copy_iv(cccbc_iv *cc_sized_by(len) iv_ctx, const void *cc_sized_by(len) iv, size_t len); 81 int cccbc_clear_iv(cccbc_iv *cc_sized_by(len) iv_ctx, size_t len); 82 83 cc_ptrcheck_unavailable() // Use cccbc_copy_iv() or cccbc_clear_iv() directly. 84 int cccbc_set_iv(const struct ccmode_cbc *mode, cccbc_iv *iv_ctx, const void *iv); 85 86 int cccbc_update(const struct ccmode_cbc *mode, const cccbc_ctx *ctx, cccbc_iv *iv, size_t nblocks, const void *cc_indexable in, void *cc_indexable out); 87 88 cc_ptrcheck_unavailable_r(cccbc_one_shot_explicit) 89 int cccbc_one_shot(const struct ccmode_cbc *mode, 90 size_t key_len, 91 const void *cc_sized_by(key_len) key, 92 const void *iv, 93 size_t nblocks, 94 const void *cc_unsafe_indexable in, 95 void *cc_unsafe_indexable out); 96 97 int cccbc_one_shot_explicit(const struct ccmode_cbc *mode, 98 size_t key_len, 99 size_t iv_len, 100 size_t block_size, 101 size_t nblocks, 102 const void *cc_sized_by(key_len) key, 103 const void *cc_sized_by(iv_len) iv, 104 const void *cc_sized_by(block_size * nblocks) in, 105 void *cc_sized_by(block_size * nblocks) out); 106 107 /* CFB mode. */ 108 109 /* Declare a cfb key named _name_. Pass the size field of a struct ccmode_cfb 110 for _size_. */ 111 #define cccfb_ctx_decl(_size_, _name_) cc_ctx_decl_vla(cccfb_ctx, _size_, _name_) 112 #define cccfb_ctx_clear(_size_, _name_) cc_clear(_size_, _name_) 113 114 size_t cccfb_context_size(const struct ccmode_cfb *mode); 115 116 size_t cccfb_block_size(const struct ccmode_cfb *mode); 117 118 int cccfb_init(const struct ccmode_cfb *mode, cccfb_ctx *ctx, size_t key_len, const void *cc_sized_by(key_len) key, const void *cc_indexable iv); 119 120 int cccfb_update(const struct ccmode_cfb *mode, cccfb_ctx *ctx, size_t nbytes, const void *cc_sized_by(nbytes) in, void *cc_sized_by(nbytes) out); 121 122 int cccfb_one_shot(const struct ccmode_cfb *mode, 123 size_t key_len, 124 const void *cc_sized_by(key_len) key, 125 const void *cc_indexable iv, 126 size_t nbytes, 127 const void *cc_sized_by(nbytes) in, 128 void *cc_sized_by(nbytes) out); 129 130 /* CFB8 mode. */ 131 132 /* Declare a cfb8 key named _name_. Pass the size field of a struct ccmode_cfb8 133 for _size_. */ 134 #define cccfb8_ctx_decl(_size_, _name_) cc_ctx_decl_vla(cccfb8_ctx, _size_, _name_) 135 #define cccfb8_ctx_clear(_size_, _name_) cc_clear(_size_, _name_) 136 137 size_t cccfb8_context_size(const struct ccmode_cfb8 *mode); 138 139 size_t cccfb8_block_size(const struct ccmode_cfb8 *mode); 140 141 int cccfb8_init(const struct ccmode_cfb8 *mode, cccfb8_ctx *ctx, size_t key_len, const void *cc_sized_by(key_len) key, const void *cc_indexable iv); 142 143 int cccfb8_update(const struct ccmode_cfb8 *mode, cccfb8_ctx *ctx, size_t nbytes, const void *cc_sized_by(nbytes) in, void *cc_sized_by(nbytes) out); 144 145 int cccfb8_one_shot(const struct ccmode_cfb8 *mode, 146 size_t key_len, 147 const void *cc_sized_by(key_len) key, 148 const void *cc_indexable iv, 149 size_t nbytes, 150 const void *cc_sized_by(nbytes) in, 151 void *cc_sized_by(nbytes) out); 152 153 /* CTR mode. */ 154 155 /* Declare a ctr key named _name_. Pass the size field of a struct ccmode_ctr 156 for _size_. */ 157 #define ccctr_ctx_decl(_size_, _name_) cc_ctx_decl_vla(ccctr_ctx, _size_, _name_) 158 #define ccctr_ctx_clear(_size_, _name_) cc_clear(_size_, _name_) 159 160 /* This is Integer Counter Mode: The IV is the initial value of the counter 161 that is incremented by 1 for each new block. Use the mode flags to select 162 if the IV/Counter is stored in big or little endian. */ 163 164 size_t ccctr_context_size(const struct ccmode_ctr *mode); 165 166 size_t ccctr_block_size(const struct ccmode_ctr *mode); 167 168 int ccctr_init(const struct ccmode_ctr *mode, ccctr_ctx *ctx, size_t key_len, const void *cc_sized_by(key_len) key, const void *cc_indexable iv); 169 170 int ccctr_update(const struct ccmode_ctr *mode, ccctr_ctx *ctx, size_t nbytes, const void *cc_sized_by(nbytes) in, void *cc_sized_by(nbytes) out); 171 172 int ccctr_one_shot(const struct ccmode_ctr *mode, 173 size_t key_len, 174 const void *cc_sized_by(key_len) key, 175 const void *cc_indexable iv, 176 size_t nbytes, 177 const void *cc_sized_by(nbytes) in, 178 void *cc_sized_by(nbytes) out); 179 180 /* OFB mode. */ 181 182 /* Declare a ofb key named _name_. Pass the size field of a struct ccmode_ofb 183 for _size_. */ 184 #define ccofb_ctx_decl(_size_, _name_) cc_ctx_decl_vla(ccofb_ctx, _size_, _name_) 185 #define ccofb_ctx_clear(_size_, _name_) cc_clear(_size_, _name_) 186 187 size_t ccofb_context_size(const struct ccmode_ofb *mode); 188 189 size_t ccofb_block_size(const struct ccmode_ofb *mode); 190 191 int ccofb_init(const struct ccmode_ofb *mode, ccofb_ctx *ctx, size_t key_len, const void *cc_sized_by(key_len) key, const void *cc_indexable iv); 192 193 int ccofb_update(const struct ccmode_ofb *mode, ccofb_ctx *ctx, size_t nbytes, const void *cc_sized_by(nbytes) in, void *cc_sized_by(nbytes) out); 194 195 int ccofb_one_shot(const struct ccmode_ofb *mode, 196 size_t key_len, 197 const void *cc_sized_by(key_len) key, 198 const void *cc_indexable iv, 199 size_t nbytes, 200 const void *cc_sized_by(nbytes) in, 201 void *cc_sized_by(nbytes) out); 202 203 /* XTS mode. */ 204 205 /* Declare a xts key named _name_. Pass the size field of a struct ccmode_xts 206 for _size_. */ 207 #define ccxts_ctx_decl(_size_, _name_) cc_ctx_decl_vla(ccxts_ctx, _size_, _name_) 208 #define ccxts_ctx_clear(_size_, _name_) cc_clear(_size_, _name_) 209 210 /* Declare a xts tweak named _name_. Pass the tweak_size field of a 211 struct ccmode_xts for _size_. */ 212 #define ccxts_tweak_decl(_size_, _name_) cc_ctx_decl_vla(ccxts_tweak, _size_, _name_) 213 #define ccxts_tweak_clear(_size_, _name_) cc_clear(_size_, _name_) 214 215 /* Actual symmetric algorithm implementation can provide you one of these. 216 217 Alternatively you can create a ccmode_xts instance from any ccmode_ecb 218 cipher. To do so, statically initialize a struct ccmode_xts using the 219 CCMODE_FACTORY_XTS_DECRYPT or CCMODE_FACTORY_XTS_ENCRYPT macros. Alternatively 220 you can dynamically initialize a struct ccmode_xts 221 ccmode_factory_xts_decrypt() or ccmode_factory_xts_encrypt(). */ 222 223 /* NOTE that xts mode does not do cts padding. It's really an xex mode. 224 If you need cts padding use the ccpad_xts_encrypt and ccpad_xts_decrypt 225 functions. Also note that xts only works for ecb modes with a block_size 226 of 16. */ 227 228 size_t ccxts_context_size(const struct ccmode_xts *mode); 229 230 size_t ccxts_block_size(const struct ccmode_xts *mode); 231 232 /*! 233 @function ccxts_init 234 @abstract Initialize an XTS context. 235 236 @param mode Descriptor for the mode 237 @param ctx Context for this instance 238 @param key_nbytes Length of the key arguments in bytes 239 @param data_key Key for data encryption 240 @param tweak_key Key for tweak generation 241 242 @result 0 iff successful. 243 244 @discussion For security reasons, the two keys must be different. 245 */ 246 int ccxts_init(const struct ccmode_xts *mode, ccxts_ctx *ctx, size_t key_nbytes, const void *cc_sized_by(key_nbytes) data_key, const void *cc_sized_by(key_nbytes) tweak_key); 247 248 /*! 249 @function ccxts_set_tweak 250 @abstract Initialize the tweak for a sector. 251 252 @param mode Descriptor for the mode 253 @param ctx Context for this instance 254 @param tweak Context for the tweak for this sector 255 @param iv Data used to generate the tweak 256 257 @discussion The IV must be exactly one block in length. 258 */ 259 int ccxts_set_tweak(const struct ccmode_xts *mode, ccxts_ctx *ctx, ccxts_tweak *tweak, const void *cc_indexable iv); 260 261 /*! 262 @function ccxts_update 263 @abstract Encrypt or decrypt data. 264 265 @param mode Descriptor for the mode 266 @param ctx Context for an instance 267 @param tweak Context for the tweak for this sector 268 @param nblocks Length of the data in blocks 269 @param in Input data 270 @param out Output buffer 271 272 @result The updated internal buffer of the tweak context. May be ignored. 273 */ 274 void *cc_unsafe_indexable 275 ccxts_update(const struct ccmode_xts *mode, ccxts_ctx *ctx, ccxts_tweak *tweak, size_t nblocks, const void *cc_indexable in, void *cc_indexable out); 276 277 /*! 278 @function ccxts_one_shot 279 @abstract Encrypt or decrypt data in XTS mode. 280 281 @param mode Descriptor for the mode 282 @param key_nbytes Length of the key arguments in bytes 283 @param data_key Key for data encryption 284 @param tweak_key Key for tweak generation 285 @param iv Data used to generate the tweak 286 @param nblocks Length of the data in blocks 287 @param in Input data 288 @param out Output buffer 289 290 @result 0 iff successful. 291 292 @discussion For security reasons, the two keys must be different. 293 */ 294 int ccxts_one_shot(const struct ccmode_xts *mode, 295 size_t key_nbytes, 296 const void *cc_sized_by(key_nbytes) data_key, 297 const void *cc_sized_by(key_nbytes) tweak_key, 298 const void *cc_unsafe_indexable iv, 299 size_t nblocks, 300 const void *cc_unsafe_indexable in, 301 void *cc_unsafe_indexable out); 302 303 /* Authenticated cipher modes. */ 304 305 /* GCM mode. */ 306 307 /* Declare a gcm key named _name_. Pass the size field of a struct ccmode_gcm 308 for _size_. */ 309 #define ccgcm_ctx_decl(_size_, _name_) cc_ctx_decl_vla(ccgcm_ctx, _size_, _name_) 310 #define ccgcm_ctx_clear(_size_, _name_) cc_clear(_size_, _name_) 311 312 #define CCGCM_IV_NBYTES 12 313 #define CCGCM_BLOCK_NBYTES 16 314 315 /* (2^32 - 2) blocks */ 316 /* (2^36 - 32) bytes */ 317 /* (2^39 - 256) bits */ 318 /* Exceeding this figure breaks confidentiality and authenticity. */ 319 #define CCGCM_TEXT_MAX_NBYTES ((1ULL << 36) - 32ULL) 320 321 size_t ccgcm_context_size(const struct ccmode_gcm *mode); 322 323 size_t ccgcm_block_size(const struct ccmode_gcm *mode); 324 325 /*! 326 @function ccgcm_init 327 @abstract Initialize a GCM context. 328 329 @param mode Descriptor for the mode 330 @param ctx Context for this instance 331 @param key_nbytes Length of the key in bytes 332 @param key Key for the underlying blockcipher (AES) 333 334 @result 0 iff successful. 335 336 @discussion The correct sequence of calls is: 337 338 @code ccgcm_init(...) 339 ccgcm_set_iv(...) 340 ccgcm_aad(...) (may be called zero or more times) 341 ccgcm_update(...) (may be called zero or more times) 342 ccgcm_finalize(...) 343 344 To reuse the context for additional encryptions, follow this sequence: 345 346 @code ccgcm_reset(...) 347 ccgcm_set_iv(...) 348 ccgcm_aad(...) (may be called zero or more times) 349 ccgcm_update(...) (may be called zero or more times) 350 ccgcm_finalize(...) 351 352 @warning The key-IV pair must be unique per encryption. The IV must be nonzero in length. 353 354 @warning It is not permitted to call @p ccgcm_inc_iv after initializing the cipher via the @p ccgcm_init interface. Nonzero is 355 returned in the event of an improper call sequence. 356 357 @warning This function is not FIPS-compliant. Use @p ccgcm_init_with_iv instead. 358 */ 359 int ccgcm_init(const struct ccmode_gcm *mode, ccgcm_ctx *ctx, size_t key_nbytes, const void *cc_sized_by(key_nbytes) key); 360 361 /*! 362 @function ccgcm_init_with_iv 363 @abstract Initialize a GCM context to manage IVs internally. 364 365 @param mode Descriptor for the mode 366 @param ctx Context for this instance 367 @param key_nbytes Length of the key in bytes 368 @param key Key for the underlying blockcipher (AES) 369 @param iv IV for the first encryption 370 371 @result 0 iff successful. 372 373 @discussion The correct sequence of calls is: 374 375 @code ccgcm_init_with_iv(...) 376 ccgcm_aad(...) (may be called zero or more times) 377 ccgcm_update(...) (may be called zero or more times) 378 ccgcm_finalize(...) 379 380 To reuse the context for additional encryptions, follow this sequence: 381 382 @code ccgcm_reset(...) 383 ccgcm_inc_iv(...) 384 ccgcm_aad(...) (may be called zero or more times) 385 ccgcm_update(...) (may be called zero or more times) 386 ccgcm_finalize(...) 387 388 The IV must be exactly 12 bytes in length. 389 390 Internally, the IV is treated as a four-byte salt followed by an eight-byte counter. This is to match the behavior of certain 391 protocols (e.g. TLS). In the call to @p ccgcm_inc_iv, the counter component will be interpreted as a big-endian, unsigned value 392 and incremented in place. 393 394 @warning It is not permitted to call @p ccgcm_set_iv after initializing the cipher via the @p ccgcm_init_with_iv interface. 395 Nonzero is returned in the event of an improper call sequence. 396 397 @warning The security of GCM depends on the uniqueness of key-IV pairs. To avoid key-IV repetition, callers should not initialize 398 multiple contexts with the same key material via the @p ccgcm_init_with_iv interface. 399 */ 400 int ccgcm_init_with_iv(const struct ccmode_gcm *mode, ccgcm_ctx *ctx, size_t key_nbytes, const void *cc_sized_by(key_nbytes) key, const void *cc_unsafe_indexable iv); 401 402 /*! 403 @function ccgcm_set_iv 404 @abstract Set the IV for encryption. 405 406 @param mode Descriptor for the mode 407 @param ctx Context for this instance 408 @param iv_nbytes Length of the IV in bytes 409 @param iv Initialization vector 410 411 @result 0 iff successful. 412 413 @discussion Set the initialization vector for encryption. 414 415 @warning The key-IV pair must be unique per encryption. The IV must be nonzero in length. 416 417 In stateful protocols, if each packet exposes a guaranteed-unique value, it is recommended to format this as a 12-byte value for 418 use as the IV. 419 420 In stateless protocols, it is recommended to choose a 16-byte value using a cryptographically-secure pseudorandom number 421 generator (e.g. @p ccrng). 422 423 @warning This function may not be used after initializing the cipher via @p ccgcm_init_with_iv. Nonzero is returned in the event 424 of an improper call sequence. 425 426 @warning This function is not FIPS-compliant. Use @p ccgcm_init_with_iv instead. 427 */ 428 int ccgcm_set_iv(const struct ccmode_gcm *mode, ccgcm_ctx *ctx, size_t iv_nbytes, const void *cc_sized_by(iv_nbytes) iv); 429 430 /*! 431 @function ccgcm_set_iv_legacy 432 @abstract Set the IV for encryption. 433 434 @param mode Descriptor for the mode 435 @param ctx Context for this instance 436 @param iv_nbytes Length of the IV in bytes 437 @param iv Initialization vector 438 439 @result 0 iff successful. 440 441 @discussion Identical to @p ccgcm_set_iv except that it allows zero-length IVs. 442 443 @warning Zero-length IVs nullify the authenticity guarantees of GCM. 444 445 @warning Do not use this function in new applications. 446 */ 447 int ccgcm_set_iv_legacy(const struct ccmode_gcm *mode, ccgcm_ctx *ctx, size_t iv_nbytes, const void *cc_sized_by(iv_nbytes) iv); 448 449 /*! 450 @function ccgcm_inc_iv 451 @abstract Increment the IV for another encryption. 452 453 @param mode Descriptor for the mode 454 @param ctx Context for this instance 455 @param iv Updated initialization vector 456 457 @result 0 iff successful. 458 459 @discussion Updates the IV internally for another encryption. 460 461 Internally, the IV is treated as a four-byte salt followed by an eight-byte counter. This is to match the behavior of certain 462 protocols (e.g. TLS). The counter component is interpreted as a big-endian, unsigned value and incremented in place. 463 464 The updated IV is copied to @p iv. This is to support protocols that require part of the IV to be specified explicitly in each 465 packet (e.g. TLS). 466 467 @warning This function may be used only after initializing the cipher via @p ccgcm_init_with_iv. 468 */ 469 int ccgcm_inc_iv(const struct ccmode_gcm *mode, ccgcm_ctx *ctx, void *cc_unsafe_indexable iv); 470 471 /*! 472 @function ccgcm_aad 473 @abstract Authenticate additional data. 474 475 @param mode Descriptor for the mode 476 @param ctx Context for this instance 477 @param nbytes Length of the additional data in bytes 478 @param additional_data Additional data to authenticate 479 480 @result 0 iff successful. 481 482 @discussion This is typically used to authenticate data that cannot be encrypted (e.g. packet headers). 483 484 This function may be called zero or more times. 485 */ 486 int ccgcm_aad(const struct ccmode_gcm *mode, ccgcm_ctx *ctx, size_t nbytes, const void *cc_sized_by(nbytes) additional_data); 487 488 /*! 489 @function ccgcm_gmac 490 491 @discussion ccgcm_gmac is deprecated. Use the drop-in replacement 'ccgcm_aad' instead. 492 */ 493 int ccgcm_gmac(const struct ccmode_gcm *mode, ccgcm_ctx *ctx, size_t nbytes, const void *cc_sized_by(nbytes) in) 494 cc_deprecate_with_replacement("ccgcm_aad", 13.0, 10.15, 13.0, 6.0, 4.0); 495 496 /*! 497 @function ccgcm_update 498 @abstract Encrypt or decrypt data. 499 500 @param mode Descriptor for the mode 501 @param ctx Context for this instance 502 @param nbytes Length of the data in bytes 503 @param in Input plaintext or ciphertext 504 @param out Output ciphertext or plaintext 505 506 @result 0 iff successful. 507 508 @discussion In-place processing is supported. 509 510 This function may be called zero or more times. 511 */ 512 int ccgcm_update(const struct ccmode_gcm *mode, ccgcm_ctx *ctx, size_t nbytes, const void *cc_sized_by(nbytes) in, void *cc_sized_by(nbytes) out); 513 514 /*! 515 @function ccgcm_finalize 516 @abstract Finish processing and authenticate. 517 518 @param mode Descriptor for the mode 519 @param ctx Context for this instance 520 @param tag_nbytes Length of the tag in bytes 521 @param tag Authentication tag 522 523 @result 0 iff successful. 524 525 @discussion Finish processing a packet and generate the authentication tag. 526 527 On encryption, @p tag is purely an output parameter. The generated tag is written to @p tag. 528 529 On decryption, @p tag is both an input and an output parameter. Well-behaved callers should provide the authentication tag 530 generated during encryption. The function will return nonzero if the input tag does not match the generated tag. The generated 531 tag will be written into the @p tag buffer whether authentication succeeds or fails. 532 533 @warning The generated tag is written to @p tag to support legacy applications that perform authentication manually. Do not 534 follow this usage pattern in new applications. Rely on the function's error code to verify authenticity. 535 */ 536 int ccgcm_finalize(const struct ccmode_gcm *mode, ccgcm_ctx *ctx, size_t tag_nbytes, void *cc_sized_by(tag_nbytes) tag); 537 538 /*! 539 @function ccgcm_reset 540 @abstract Reset the context for another encryption. 541 542 @param mode Descriptor for the mode 543 @param ctx Context for this instance 544 545 @result 0 iff successful. 546 547 @discussion Refer to @p ccgcm_init for correct usage. 548 */ 549 int ccgcm_reset(const struct ccmode_gcm *mode, ccgcm_ctx *ctx); 550 551 /*! 552 @function ccgcm_one_shot 553 @abstract Encrypt or decrypt with GCM. 554 555 @param mode Descriptor for the mode 556 @param key_nbytes Length of the key in bytes 557 @param key Key for the underlying blockcipher (AES) 558 @param iv_nbytes Length of the IV in bytes 559 @param iv Initialization vector 560 @param adata_nbytes Length of the additional data in bytes 561 @param adata Additional data to authenticate 562 @param nbytes Length of the data in bytes 563 @param in Input plaintext or ciphertext 564 @param out Output ciphertext or plaintext 565 @param tag_nbytes Length of the tag in bytes 566 @param tag Authentication tag 567 568 @result 0 iff successful. 569 570 @discussion Perform GCM encryption or decryption. 571 572 @warning The key-IV pair must be unique per encryption. The IV must be nonzero in length. 573 574 In stateful protocols, if each packet exposes a guaranteed-unique value, it is recommended to format this as a 12-byte value for 575 use as the IV. 576 577 In stateless protocols, it is recommended to choose a 16-byte value using a cryptographically-secure pseudorandom number 578 generator (e.g. @p ccrng). 579 580 In-place processing is supported. 581 582 On encryption, @p tag is purely an output parameter. The generated tag is written to @p tag. 583 584 On decryption, @p tag is primarily an input parameter. The caller should provide the authentication tag generated during 585 encryption. The function will return nonzero if the input tag does not match the generated tag. 586 587 @warning To support legacy applications, @p tag is also an output parameter during decryption. The generated tag is written to @p 588 tag. Legacy callers may choose to compare this to the tag generated during encryption. Do not follow this usage pattern in new 589 applications. 590 */ 591 int ccgcm_one_shot(const struct ccmode_gcm *mode, 592 size_t key_nbytes, 593 const void *cc_sized_by(key_nbytes) key, 594 size_t iv_nbytes, 595 const void *cc_sized_by(iv_nbytes) iv, 596 size_t adata_nbytes, 597 const void *cc_sized_by(adata_nbytes) adata, 598 size_t nbytes, 599 const void *cc_sized_by(nbytes) in, 600 void *cc_sized_by(nbytes) out, 601 size_t tag_nbytes, 602 void *cc_sized_by(tag_nbytes) tag); 603 604 /*! 605 @function ccgcm_one_shot_legacy 606 @abstract Encrypt or decrypt with GCM. 607 608 @param mode Descriptor for the mode 609 @param key_nbytes Length of the key in bytes 610 @param key Key for the underlying blockcipher (AES) 611 @param iv_nbytes Length of the IV in bytes 612 @param iv Initialization vector 613 @param adata_nbytes Length of the additional data in bytes 614 @param adata Additional data to authenticate 615 @param nbytes Length of the data in bytes 616 @param in Input plaintext or ciphertext 617 @param out Output ciphertext or plaintext 618 @param tag_nbytes Length of the tag in bytes 619 @param tag Authentication tag 620 621 @result 0 iff successful. 622 623 @discussion Identical to @p ccgcm_one_shot except that it allows zero-length IVs. 624 625 @warning Zero-length IVs nullify the authenticity guarantees of GCM. 626 627 @warning Do not use this function in new applications. 628 */ 629 int ccgcm_one_shot_legacy(const struct ccmode_gcm *mode, 630 size_t key_nbytes, 631 const void *cc_sized_by(key_nbytes) key, 632 size_t iv_nbytes, 633 const void *cc_sized_by(iv_nbytes) iv, 634 size_t adata_nbytes, 635 const void *cc_sized_by(adata_nbytes) adata, 636 size_t nbytes, 637 const void *cc_sized_by(nbytes) in, 638 void *cc_sized_by(nbytes) out, 639 size_t tag_nbytes, 640 void *cc_sized_by(tag_nbytes) tag); 641 642 /* CCM */ 643 #define CCM_MAX_TAG_SIZE 16 644 #define ccccm_ctx_decl(_size_, _name_) cc_ctx_decl_vla(ccccm_ctx, _size_, _name_) 645 #define ccccm_ctx_clear(_size_, _name_) cc_clear(_size_, _name_) 646 647 /* Declare a ccm nonce named _name_. Pass the mode->nonce_ctx_size for _size_. */ 648 #define ccccm_nonce_decl(_size_, _name_) cc_ctx_decl_vla(ccccm_nonce, _size_, _name_) 649 #define ccccm_nonce_clear(_size_, _name_) cc_clear(_size_, _name_) 650 651 size_t ccccm_context_size(const struct ccmode_ccm *mode); 652 653 size_t ccccm_block_size(const struct ccmode_ccm *mode); 654 655 /// Initialize a ccm authenticated encryption/decryption mode 656 /// @param mode mode descriptor 657 /// @param ctx context for this instance 658 /// @param key_len length in bytes of key provided 659 /// @param key bytes defining key 660 int ccccm_init(const struct ccmode_ccm *mode, ccccm_ctx *ctx, size_t key_len, const void *cc_sized_by(key_len) key); 661 662 /// Set the initialization value/nonce for the ccm authenticated encryption/decryption 663 /// @param mode mode descriptor 664 /// @param ctx context for this ccm instance 665 /// @param nonce_ctx context for this nonce 666 /// @param nonce_len length in bytes of cmac nonce/iv 667 /// @param nonce bytes defining none 668 /// @param mac_size length in bytes of mac tag 669 /// @param auth_len length in bytes of authenticating data 670 /// @param data_len length in bytes of plaintext 671 int ccccm_set_iv(const struct ccmode_ccm *mode, 672 ccccm_ctx *ctx, 673 ccccm_nonce *nonce_ctx, 674 size_t nonce_len, 675 const void *cc_sized_by(nonce_len) nonce, 676 size_t mac_size, 677 size_t auth_len, 678 size_t data_len); 679 680 /// (Deprecated) Add associated data to the ccm authenticated encryption/decryption 681 /// @param mode mode descriptor 682 /// @param ctx context for this ccm instance 683 /// @param nonce_ctx context for this nonce 684 /// @param nbytes nbytes length in bytes of associated data being provided in this invocation 685 /// @param in authenticated data being provided in this invocation 686 int ccccm_cbcmac(const struct ccmode_ccm *mode, ccccm_ctx *ctx, ccccm_nonce *nonce_ctx, size_t nbytes, const void *cc_sized_by(nbytes) in); 687 688 ///Add associated data to the ccm authenticated encryption/decryption 689 /// @param mode mode descriptor 690 /// @param ctx context for this ccm instance 691 /// @param nonce_ctx context for this nonce 692 /// @param ad_nbytes nbytes length in bytes of associated data being provided in this invocation 693 /// @param ad authenticated data being provided in this invocation 694 int ccccm_aad(const struct ccmode_ccm *mode, ccccm_ctx *ctx, ccccm_nonce *nonce_ctx, size_t ad_nbytes, const uint8_t *cc_sized_by(ad_nbytes) ad); 695 696 /// Add plaintext data to the ccm authenticated encryption/decryption 697 /// @param mode mode descriptor 698 /// @param ctx context for this ccm instance 699 /// @param nonce_ctx context for this nonce 700 /// @param nbytes length in bytes of both plaintext and encrypted plaintext 701 /// @param in In encryption mode plaintext data, in decryption mode encrypted plaintext data. 702 /// @param out in encryption mode resulting encrypted plaintext data. In decryption mode resulting plaintext data 703 int ccccm_update(const struct ccmode_ccm *mode, ccccm_ctx *ctx, ccccm_nonce *nonce_ctx, size_t nbytes, const void *cc_sized_by(nbytes) in, void *cc_sized_by(nbytes) out); 704 705 /// Add plaintext data to the ccm authenticated encryption 706 /// @param mode mode descriptor 707 /// @param ctx context for this ccm instance 708 /// @param nonce_ctx context for this nonce 709 /// @param nbytes length in bytes of both plaintext and encrypted plaintext 710 /// @param plaintext In encryption mode plaintext data, in decryption mode encrypted plaintext data. 711 /// @param encrypted_plaintext in encryption mode resulting encrypted plaintext data. In decryption mode resulting plaintext data 712 int ccccm_encrypt(const struct ccmode_ccm *mode, ccccm_ctx *ctx, ccccm_nonce *nonce_ctx, size_t nbytes, const uint8_t *cc_sized_by(nbytes) plaintext, uint8_t *cc_sized_by(nbytes) encrypted_plaintext); 713 714 /// Add ciphertext data to the ccm authenticated decryption 715 /// @param mode mode descriptor 716 /// @param ctx context for this ccm instance 717 /// @param nonce_ctx context for this nonce 718 /// @param nbytes length in bytes of both plaintext and encrypted plaintext 719 /// @param encrypted_plaintext In encryption mode plaintext data, in decryption mode encrypted plaintext data. 720 /// @param plaintext in encryption mode resulting encrypted plaintext data. In decryption mode resulting plaintext data 721 int ccccm_decrypt(const struct ccmode_ccm *mode, ccccm_ctx *ctx, ccccm_nonce *nonce_ctx, size_t nbytes, const uint8_t *cc_sized_by(nbytes) encrypted_plaintext, uint8_t *cc_sized_by(nbytes) plaintext); 722 723 724 /// (Deprecated) Compute tag for ccm 725 /// @param mode mode descriptor 726 /// @param ctx context for this ccm instance 727 /// @param nonce_ctx context for this nonce 728 /// @param mac tag portion of ciphertext that is computed from ccm MAC. 729 /// @discussion This is being deprecated, as it requires the caller to manually verify that the returned mac tag is correct when decrypting. Please use ccccm_finalize_and_verify instead. 730 int ccccm_finalize(const struct ccmode_ccm *mode, ccccm_ctx *ctx, ccccm_nonce *nonce_ctx, void *cc_indexable mac); 731 732 /// Ends encryption and computes tag when in encryption mode 733 /// @param mode mode descriptor 734 /// @param ctx context for this ccm instance 735 /// @param nonce_ctx context for this nonce 736 /// @param mac For encryption mode the resulting mac tag portion of the ciphertext is copied to this buffer. For decryption mode, it provides an input of the expected tag in the ciphertext 737 /// @return For decryption returns CCERR_OK if the provided mac matches the computed mac, and otherwise returns CCMODE_INTEGRITY_FAILURE. 738 int ccccm_finalize_and_generate_tag(const struct ccmode_ccm *mode, ccccm_ctx *ctx, ccccm_nonce *nonce_ctx, uint8_t *cc_indexable mac); 739 740 /// Ends decryption and verifies tag when in decryption mode 741 /// @param mode mode descriptor 742 /// @param ctx context for this ccm instance 743 /// @param nonce_ctx context for this nonce 744 /// @param mac It provides an input of the expected tag in the ciphertext 745 /// @return Returns CCERR_OK if the provided mac matches the computed mac, and otherwise returns CCMODE_INTEGRITY_FAILURE. 746 int ccccm_finalize_and_verify_tag(const struct ccmode_ccm *mode, ccccm_ctx *ctx, ccccm_nonce *nonce_ctx, const uint8_t *cc_indexable mac); 747 748 /// Resets the state of the encryptor/decryptor, maintaining the key, but clearing the nonce/iv, allowing for a new encryption or decryption 749 /// @param mode mode descriptor 750 /// @param ctx context for this ccm instance 751 /// @param nonce_ctx context for this nonce 752 int ccccm_reset(const struct ccmode_ccm *mode, ccccm_ctx *ctx, ccccm_nonce *nonce_ctx); 753 754 /// (Deprecated) Encrypts/Decrypts a plaintext/ciphertext using the AEAD CCM mode. 755 /// @param mode mode descriptor 756 /// @param key_len key length in bytes 757 /// @param key buffer holding key 758 /// @param nonce_len nonce length in bytes 759 /// @param nonce buffer holding nonce 760 /// @param nbytes the length of the plaintext and encrypted-plaintext 761 /// @param in buffer holding plaintext in encryption mode, and encrypted plaintext portion of ciphertext in decryption mode 762 /// @param out buffer receiving resulting encrypted plaintext in encryption mode, and resulting plaintext in decryption mode 763 /// @param adata_len length in bytes of associated data 764 /// @param adata authenticated data being provided in this invocation. 765 /// @param mac_size length in bytes of CCM mac tag 766 /// @param mac portion of ciphertext that is computed from ccm MAC. 767 /// @return This is being deprecated, as it requires the caller to manually verify that the returned mac tag is correct when decrypting. Please use ccccm_one_shot_with_verify instead 768 int ccccm_one_shot(const struct ccmode_ccm *mode, 769 size_t key_len, 770 const void *cc_sized_by(key_len) key, 771 size_t nonce_len, 772 const void *cc_sized_by(nonce_len) nonce, 773 size_t nbytes, 774 const void *cc_sized_by(nbytes) in, 775 void *cc_sized_by(nbytes) out, 776 size_t adata_len, 777 const void *cc_sized_by(adata_len) adata, 778 size_t mac_size, 779 void *cc_sized_by(mac_size) mac); 780 781 /// Encrypts a plaintext using the AEAD CCM mode, and provides corresponding mac tag. The encrypted plaintext and tag together are the AEAD ciphertext 782 /// @param mode mode descriptor 783 /// @param key_nbytes key length in bytes 784 /// @param key buffer holding key 785 /// @param nonce_nbytes nonce length in bytes 786 /// @param nonce buffer holding nonce 787 /// @param nbytes the length of the plaintext and encrypted-plaintext 788 /// @param plaintext buffer holding plaintext in encryption mode, and encrypted plaintext portion of ciphertext in decryption mode 789 /// @param encrypted_plaintext buffer receiving resulting encrypted plaintext in encryption mode 790 /// @param adata_nbytes length in bytes of associated data 791 /// @param adata authenticated data being provided in this invocation. 792 /// @param mac_tag_nbytes length in bytes of CCM mac tag 793 /// @param mac_tag portion of ciphertext that is computed from ccm MAC. 794 /// @return CERR_OK on successful encryption 795 int ccccm_one_shot_encrypt(const struct ccmode_ccm *mode, 796 size_t key_nbytes, 797 const uint8_t *cc_sized_by(key_nbytes) key, 798 size_t nonce_nbytes, 799 const uint8_t *cc_sized_by(nonce_nbytes) nonce, 800 size_t nbytes, 801 const uint8_t *cc_sized_by(nbytes) plaintext, 802 uint8_t *cc_sized_by(nbytes) encrypted_plaintext, 803 size_t adata_nbytes, 804 const uint8_t *cc_sized_by(adata_nbytes) adata, 805 size_t mac_tag_nbytes, 806 uint8_t *cc_sized_by(mac_tag_nbytes) mac_tag); 807 808 /// Decrypts a ciphertext using the AEAD CCM mode and ensures authenticity of the ciphertext. An AEAD CCM ciphertext consists of encrypted plaintext and mac tag 809 /// @param mode mode descriptor 810 /// @param key_nbytes key length in bytes 811 /// @param key buffer holding key 812 /// @param nonce_nbytes nonce length in bytes 813 /// @param nonce buffer holding nonce 814 /// @param nbytes the length of the plaintext and encrypted-plaintext 815 /// @param encrypted_plaintext buffer holding the encrypted plaintext portion of ciphertext 816 /// @param plaintext buffer receiving resulting plaintext 817 /// @param adata_nbytes length in bytes of associated data 818 /// @param adata authenticated data being provided in this invocation. 819 /// @param mac_tag_nbytes length in bytes of CCM mac tag 820 /// @param mac_tag portion of ciphertext that is computed from ccm MAC. 821 /// @return For decryption returns CCERR_OK if the provided mac matches the computed mac, and otherwise returns CCMODE_INTEGRITY_FAILURE. 822 int ccccm_one_shot_decrypt(const struct ccmode_ccm *mode, 823 size_t key_nbytes, 824 const uint8_t *cc_sized_by(key_nbytes) key, 825 size_t nonce_nbytes, 826 const uint8_t *cc_sized_by(nonce_nbytes) nonce, 827 size_t nbytes, 828 const uint8_t *cc_sized_by(nbytes) encrypted_plaintext, 829 uint8_t *cc_sized_by(nbytes) plaintext, 830 size_t adata_nbytes, 831 const uint8_t *cc_sized_by(adata_nbytes) adata, 832 size_t mac_tag_nbytes, 833 const uint8_t *cc_sized_by(mac_tag_nbytes) mac_tag); 834 835 /* OMAC mode. */ 836 837 /* Declare a omac key named _name_. Pass the size field of a struct ccmode_omac 838 for _size_. */ 839 #define ccomac_ctx_decl(_size_, _name_) cc_ctx_decl_vla(ccomac_ctx, _size_, _name_) 840 #define ccomac_ctx_clear(_size_, _name_) cc_clear(_size_, _name_) 841 842 size_t ccomac_context_size(const struct ccmode_omac *mode); 843 844 size_t ccomac_block_size(const struct ccmode_omac *mode); 845 846 int ccomac_init(const struct ccmode_omac *mode, ccomac_ctx *ctx, size_t tweak_len, size_t key_len, const void *cc_sized_by(key_len) key); 847 848 int ccomac_update(const struct ccmode_omac *mode, ccomac_ctx *ctx, size_t nblocks, const void *tweak, const void *cc_indexable in, void *cc_indexable out); 849 850 int ccomac_one_shot(const struct ccmode_omac *mode, 851 size_t tweak_len, 852 size_t key_len, 853 const void *cc_sized_by(key_len) key, 854 const void *cc_sized_by(tweak_len) tweak, 855 size_t nblocks, 856 const void *cc_indexable in, 857 void *cc_indexable out); 858 859 #endif /* _CORECRYPTO_CCMODE_H_ */ 860