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
21CC_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
30size_t ccecb_context_size(const struct ccmode_ecb *mode);
31
32size_t ccecb_block_size(const struct ccmode_ecb *mode);
33
34int ccecb_init(const struct ccmode_ecb *mode, ccecb_ctx *ctx, size_t key_len, const void *cc_sized_by(key_len) key);
35
36int ccecb_update(const struct ccmode_ecb *mode, const ccecb_ctx *ctx, size_t nblocks, const void *cc_indexable in, void *cc_indexable out);
37
38cc_ptrcheck_unavailable_r(ccecb_one_shot_explicit)
39int 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
46int 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
74size_t cccbc_context_size(const struct ccmode_cbc *mode);
75
76size_t cccbc_block_size(const struct ccmode_cbc *mode);
77
78int cccbc_init(const struct ccmode_cbc *mode, cccbc_ctx *ctx, size_t key_len, const void *cc_sized_by(key_len) key);
79
80int cccbc_copy_iv(cccbc_iv *cc_sized_by(len) iv_ctx, const void *cc_sized_by(len) iv, size_t len);
81int cccbc_clear_iv(cccbc_iv *cc_sized_by(len) iv_ctx, size_t len);
82
83cc_ptrcheck_unavailable() // Use cccbc_copy_iv() or cccbc_clear_iv() directly.
84int cccbc_set_iv(const struct ccmode_cbc *mode, cccbc_iv *iv_ctx, const void *iv);
85
86int 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
88cc_ptrcheck_unavailable_r(cccbc_one_shot_explicit)
89int 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
97int 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
114size_t cccfb_context_size(const struct ccmode_cfb *mode);
115
116size_t cccfb_block_size(const struct ccmode_cfb *mode);
117
118int 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
120int 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
122int 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
137size_t cccfb8_context_size(const struct ccmode_cfb8 *mode);
138
139size_t cccfb8_block_size(const struct ccmode_cfb8 *mode);
140
141int 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
143int 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
145int 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
164size_t ccctr_context_size(const struct ccmode_ctr *mode);
165
166size_t ccctr_block_size(const struct ccmode_ctr *mode);
167
168int 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
170int 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
172int 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
187size_t ccofb_context_size(const struct ccmode_ofb *mode);
188
189size_t ccofb_block_size(const struct ccmode_ofb *mode);
190
191int 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
193int 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
195int 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
228size_t ccxts_context_size(const struct ccmode_xts *mode);
229
230size_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 */
246int 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 */
259int 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 */
274void *cc_unsafe_indexable
275ccxts_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 */
294int 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
321size_t ccgcm_context_size(const struct ccmode_gcm *mode);
322
323size_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 */
359int 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 */
400int 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 */
428int 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 */
447int 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 */
469int 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 */
486int 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 */
493int ccgcm_gmac(const struct ccmode_gcm *mode, ccgcm_ctx *ctx, size_t nbytes, const void *cc_sized_by(nbytes) in)
494cc_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 */
512int 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 */
536int 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 */
549int 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 */
591int 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 */
629int 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
651size_t ccccm_context_size(const struct ccmode_ccm *mode);
652
653size_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
660int 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
671int 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
686int 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
694int 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
703int 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
712int 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
721int 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.
730int 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.
738int 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.
746int 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
752int 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
768int 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
795int 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.
822int 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
842size_t ccomac_context_size(const struct ccmode_omac *mode);
843
844size_t ccomac_block_size(const struct ccmode_omac *mode);
845
846int 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
848int 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
850int 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