Fixed some errors in comments.
[BearSSL] / inc / bearssl_aead.h
1 /*
2 * Copyright (c) 2017 Thomas Pornin <pornin@bolet.org>
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 */
24
25 #ifndef BR_BEARSSL_AEAD_H__
26 #define BR_BEARSSL_AEAD_H__
27
28 #include <stddef.h>
29 #include <stdint.h>
30
31 #include "bearssl_block.h"
32 #include "bearssl_hash.h"
33
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37
38 /** \file bearssl_aead.h
39 *
40 * # Authenticated Encryption with Additional Data
41 *
42 * This file documents the API for AEAD encryption.
43 *
44 *
45 * ## Procedural API
46 *
47 * An AEAD algorithm processes messages and provides confidentiality
48 * (encryption) and checked integrity (MAC). It uses the following
49 * parameters:
50 *
51 * - A symmetric key. Exact size depends on the AEAD algorithm.
52 *
53 * - A nonce (IV). Size depends on the AEAD algorithm; for most
54 * algorithms, it is crucial for security that any given nonce
55 * value is never used twice for the same key and distinct
56 * messages.
57 *
58 * - Data to encrypt and protect.
59 *
60 * - Additional authenticated data, which is covered by the MAC but
61 * otherwise left untouched (i.e. not encrypted).
62 *
63 * The AEAD algorithm encrypts the data, and produces an authentication
64 * tag. It is assumed that the encrypted data, the tag, the additional
65 * authenticated data and the nonce are sent to the receiver; the
66 * additional data and the nonce may be implicit (e.g. using elements of
67 * the underlying transport protocol, such as record sequence numbers).
68 * The receiver will recompute the tag value and compare it with the one
69 * received; if they match, then the data is correct, and can be
70 * decrypted and used; otherwise, at least one of the elements was
71 * altered in transit, normally leading to wholesale rejection of the
72 * complete message.
73 *
74 * For each AEAD algorithm, identified by a symbolic name (hereafter
75 * denoted as "`xxx`"), the following functions are defined:
76 *
77 * - `br_xxx_init()`
78 *
79 * Initialise the AEAD algorithm, on a provided context structure.
80 * Exact parameters depend on the algorithm, and may include
81 * pointers to extra implementations and context structures. The
82 * secret key is provided at this point, either directly or
83 * indirectly.
84 *
85 * - `br_xxx_reset()`
86 *
87 * Start a new AEAD computation. The nonce value is provided as
88 * parameter to this function.
89 *
90 * - `br_xxx_aad_inject()`
91 *
92 * Inject some additional authenticated data. Additional data may
93 * be provided in several chunks of arbitrary length.
94 *
95 * - `br_xxx_flip()`
96 *
97 * This function MUST be called after injecting all additional
98 * authenticated data, and before beginning to encrypt the plaintext
99 * (or decrypt the ciphertext).
100 *
101 * - `br_xxx_run()`
102 *
103 * Process some plaintext (to encrypt) or ciphertext (to decrypt).
104 * Encryption/decryption is done in place. Data may be provided in
105 * several chunks of arbitrary length.
106 *
107 * - `br_xxx_get_tag()`
108 *
109 * Compute the authentication tag. All message data (encrypted or
110 * decrypted) must have been injected at that point. Also, this
111 * call may modify internal context elements, so it may be called
112 * only once for a given AEAD computation.
113 *
114 * - `br_xxx_check_tag()`
115 *
116 * An alternative to `br_xxx_get_tag()`, meant to be used by the
117 * receiver: the authentication tag is internally recomputed, and
118 * compared with the one provided as parameter.
119 *
120 * This API makes the following assumptions on the AEAD algorithm:
121 *
122 * - Encryption does not expand the size of the ciphertext; there is
123 * no padding. This is true of most modern AEAD modes such as GCM.
124 *
125 * - The additional authenticated data must be processed first,
126 * before the encrypted/decrypted data.
127 *
128 * - Nonce, plaintext and additional authenticated data all consist
129 * in an integral number of bytes. There is no provision to use
130 * elements whose length in bits is not a multiple of 8.
131 *
132 * Each AEAD algorithm has its own requirements and limits on the sizes
133 * of additional data and plaintext. This API does not provide any
134 * way to report invalid usage; it is up to the caller to ensure that
135 * the provided key, nonce, and data elements all fit the algorithm's
136 * requirements.
137 *
138 *
139 * ## Object-Oriented API
140 *
141 * Each context structure begins with a field (called `vtable`) that
142 * points to an instance of a structure that references the relevant
143 * functions through pointers. Each such structure contains the
144 * following:
145 *
146 * - `reset`
147 *
148 * Pointer to the reset function, that allows starting a new
149 * computation.
150 *
151 * - `aad_inject`
152 *
153 * Pointer to the additional authenticated data injection function.
154 *
155 * - `flip`
156 *
157 * Pointer to the function that transitions from additional data
158 * to main message data processing.
159 *
160 * - `get_tag`
161 *
162 * Pointer to the function that computes and returns the tag.
163 *
164 * - `check_tag`
165 *
166 * Pointer to the function that computes and verifies the tag against
167 * a received value.
168 *
169 * Note that there is no OOP method for context initialisation: the
170 * various AEAD algorithms have different requirements that would not
171 * map well to a single initialisation API.
172 *
173 * The OOP API is not provided for CCM, due to its specific requirements
174 * (length of plaintext must be known in advance).
175 */
176
177 /**
178 * \brief Class type of an AEAD algorithm.
179 */
180 typedef struct br_aead_class_ br_aead_class;
181 struct br_aead_class_ {
182
183 /**
184 * \brief Size (in bytes) of authentication tags created by
185 * this AEAD algorithm.
186 */
187 size_t tag_size;
188
189 /**
190 * \brief Reset an AEAD context.
191 *
192 * This function resets an already initialised AEAD context for
193 * a new computation run. Implementations and keys are
194 * conserved. This function can be called at any time; it
195 * cancels any ongoing AEAD computation that uses the provided
196 * context structure.
197
198 * The provided IV is a _nonce_. Each AEAD algorithm has its
199 * own requirements on IV size and contents; for most of them,
200 * it is crucial to security that each nonce value is used
201 * only once for a given secret key.
202 *
203 * \param cc AEAD context structure.
204 * \param iv AEAD nonce to use.
205 * \param len AEAD nonce length (in bytes).
206 */
207 void (*reset)(const br_aead_class **cc, const void *iv, size_t len);
208
209 /**
210 * \brief Inject additional authenticated data.
211 *
212 * The provided data is injected into a running AEAD
213 * computation. Additional data must be injected _before_ the
214 * call to `flip()`. Additional data can be injected in several
215 * chunks of arbitrary length.
216 *
217 * \param cc AEAD context structure.
218 * \param data pointer to additional authenticated data.
219 * \param len length of additional authenticated data (in bytes).
220 */
221 void (*aad_inject)(const br_aead_class **cc,
222 const void *data, size_t len);
223
224 /**
225 * \brief Finish injection of additional authenticated data.
226 *
227 * This function MUST be called before beginning the actual
228 * encryption or decryption (with `run()`), even if no
229 * additional authenticated data was injected. No additional
230 * authenticated data may be injected after this function call.
231 *
232 * \param cc AEAD context structure.
233 */
234 void (*flip)(const br_aead_class **cc);
235
236 /**
237 * \brief Encrypt or decrypt some data.
238 *
239 * Data encryption or decryption can be done after `flip()` has
240 * been called on the context. If `encrypt` is non-zero, then
241 * the provided data shall be plaintext, and it is encrypted in
242 * place. Otherwise, the data shall be ciphertext, and it is
243 * decrypted in place.
244 *
245 * Data may be provided in several chunks of arbitrary length.
246 *
247 * \param cc AEAD context structure.
248 * \param encrypt non-zero for encryption, zero for decryption.
249 * \param data data to encrypt or decrypt.
250 * \param len data length (in bytes).
251 */
252 void (*run)(const br_aead_class **cc, int encrypt,
253 void *data, size_t len);
254
255 /**
256 * \brief Compute authentication tag.
257 *
258 * Compute the AEAD authentication tag. The tag length depends
259 * on the AEAD algorithm; it is written in the provided `tag`
260 * buffer. This call terminates the AEAD run: no data may be
261 * processed with that AEAD context afterwards, until `reset()`
262 * is called to initiate a new AEAD run.
263 *
264 * The tag value must normally be sent along with the encrypted
265 * data. When decrypting, the tag value must be recomputed and
266 * compared with the received tag: if the two tag values differ,
267 * then either the tag or the encrypted data was altered in
268 * transit. As an alternative to this function, the
269 * `check_tag()` function may be used to compute and check the
270 * tag value.
271 *
272 * Tag length depends on the AEAD algorithm.
273 *
274 * \param cc AEAD context structure.
275 * \param tag destination buffer for the tag.
276 */
277 void (*get_tag)(const br_aead_class **cc, void *tag);
278
279 /**
280 * \brief Compute and check authentication tag.
281 *
282 * This function is an alternative to `get_tag()`, and is
283 * normally used on the receiving end (i.e. when decrypting
284 * messages). The tag value is recomputed and compared with the
285 * provided tag value. If they match, 1 is returned; on
286 * mismatch, 0 is returned. A returned value of 0 means that the
287 * data or the tag was altered in transit, normally leading to
288 * wholesale rejection of the complete message.
289 *
290 * Tag length depends on the AEAD algorithm.
291 *
292 * \param cc AEAD context structure.
293 * \param tag tag value to compare with.
294 * \return 1 on success (exact match of tag value), 0 otherwise.
295 */
296 uint32_t (*check_tag)(const br_aead_class **cc, const void *tag);
297
298 /**
299 * \brief Compute authentication tag (with truncation).
300 *
301 * This function is similar to `get_tag()`, except that the tag
302 * length is provided. Some AEAD algorithms allow several tag
303 * lengths, usually by truncating the normal tag. Shorter tags
304 * mechanically increase success probability of forgeries.
305 * The range of allowed tag lengths depends on the algorithm.
306 *
307 * \param cc AEAD context structure.
308 * \param tag destination buffer for the tag.
309 * \param len tag length (in bytes).
310 */
311 void (*get_tag_trunc)(const br_aead_class **cc, void *tag, size_t len);
312
313 /**
314 * \brief Compute and check authentication tag (with truncation).
315 *
316 * This function is similar to `check_tag()` except that it
317 * works over an explicit tag length. See `get_tag()` for a
318 * discussion of explicit tag lengths; the range of allowed tag
319 * lengths depends on the algorithm.
320 *
321 * \param cc AEAD context structure.
322 * \param tag tag value to compare with.
323 * \param len tag length (in bytes).
324 * \return 1 on success (exact match of tag value), 0 otherwise.
325 */
326 uint32_t (*check_tag_trunc)(const br_aead_class **cc,
327 const void *tag, size_t len);
328 };
329
330 /**
331 * \brief Context structure for GCM.
332 *
333 * GCM is an AEAD mode that combines a block cipher in CTR mode with a
334 * MAC based on GHASH, to provide authenticated encryption:
335 *
336 * - Any block cipher with 16-byte blocks can be used with GCM.
337 *
338 * - The nonce can have any length, from 0 up to 2^64-1 bits; however,
339 * 96-bit nonces (12 bytes) are recommended (nonces with a length
340 * distinct from 12 bytes are internally hashed, which risks reusing
341 * nonce value with a small but not always negligible probability).
342 *
343 * - Additional authenticated data may have length up to 2^64-1 bits.
344 *
345 * - Message length may range up to 2^39-256 bits at most.
346 *
347 * - The authentication tag has length 16 bytes.
348 *
349 * The GCM initialisation function receives as parameter an
350 * _initialised_ block cipher implementation context, with the secret
351 * key already set. A pointer to that context will be kept within the
352 * GCM context structure. It is up to the caller to allocate and
353 * initialise that block cipher context.
354 */
355 typedef struct {
356 /** \brief Pointer to vtable for this context. */
357 const br_aead_class *vtable;
358
359 #ifndef BR_DOXYGEN_IGNORE
360 const br_block_ctr_class **bctx;
361 br_ghash gh;
362 unsigned char h[16];
363 unsigned char j0_1[12];
364 unsigned char buf[16];
365 unsigned char y[16];
366 uint32_t j0_2, jc;
367 uint64_t count_aad, count_ctr;
368 #endif
369 } br_gcm_context;
370
371 /**
372 * \brief Initialize a GCM context.
373 *
374 * A block cipher implementation, with its initialised context structure,
375 * is provided. The block cipher MUST use 16-byte blocks in CTR mode,
376 * and its secret key MUST have been already set in the provided context.
377 * A GHASH implementation must also be provided. The parameters are linked
378 * in the GCM context.
379 *
380 * After this function has been called, the `br_gcm_reset()` function must
381 * be called, to provide the IV for GCM computation.
382 *
383 * \param ctx GCM context structure.
384 * \param bctx block cipher context (already initialised with secret key).
385 * \param gh GHASH implementation.
386 */
387 void br_gcm_init(br_gcm_context *ctx,
388 const br_block_ctr_class **bctx, br_ghash gh);
389
390 /**
391 * \brief Reset a GCM context.
392 *
393 * This function resets an already initialised GCM context for a new
394 * computation run. Implementations and keys are conserved. This function
395 * can be called at any time; it cancels any ongoing GCM computation that
396 * uses the provided context structure.
397 *
398 * The provided IV is a _nonce_. It is critical to GCM security that IV
399 * values are not repeated for the same encryption key. IV can have
400 * arbitrary length (up to 2^64-1 bits), but the "normal" length is
401 * 96 bits (12 bytes).
402 *
403 * \param ctx GCM context structure.
404 * \param iv GCM nonce to use.
405 * \param len GCM nonce length (in bytes).
406 */
407 void br_gcm_reset(br_gcm_context *ctx, const void *iv, size_t len);
408
409 /**
410 * \brief Inject additional authenticated data into GCM.
411 *
412 * The provided data is injected into a running GCM computation. Additional
413 * data must be injected _before_ the call to `br_gcm_flip()`.
414 * Additional data can be injected in several chunks of arbitrary length;
415 * the maximum total size of additional authenticated data is 2^64-1
416 * bits.
417 *
418 * \param ctx GCM context structure.
419 * \param data pointer to additional authenticated data.
420 * \param len length of additional authenticated data (in bytes).
421 */
422 void br_gcm_aad_inject(br_gcm_context *ctx, const void *data, size_t len);
423
424 /**
425 * \brief Finish injection of additional authenticated data into GCM.
426 *
427 * This function MUST be called before beginning the actual encryption
428 * or decryption (with `br_gcm_run()`), even if no additional authenticated
429 * data was injected. No additional authenticated data may be injected
430 * after this function call.
431 *
432 * \param ctx GCM context structure.
433 */
434 void br_gcm_flip(br_gcm_context *ctx);
435
436 /**
437 * \brief Encrypt or decrypt some data with GCM.
438 *
439 * Data encryption or decryption can be done after `br_gcm_flip()`
440 * has been called on the context. If `encrypt` is non-zero, then the
441 * provided data shall be plaintext, and it is encrypted in place.
442 * Otherwise, the data shall be ciphertext, and it is decrypted in place.
443 *
444 * Data may be provided in several chunks of arbitrary length. The maximum
445 * total length for data is 2^39-256 bits, i.e. about 65 gigabytes.
446 *
447 * \param ctx GCM context structure.
448 * \param encrypt non-zero for encryption, zero for decryption.
449 * \param data data to encrypt or decrypt.
450 * \param len data length (in bytes).
451 */
452 void br_gcm_run(br_gcm_context *ctx, int encrypt, void *data, size_t len);
453
454 /**
455 * \brief Compute GCM authentication tag.
456 *
457 * Compute the GCM authentication tag. The tag is a 16-byte value which
458 * is written in the provided `tag` buffer. This call terminates the
459 * GCM run: no data may be processed with that GCM context afterwards,
460 * until `br_gcm_reset()` is called to initiate a new GCM run.
461 *
462 * The tag value must normally be sent along with the encrypted data.
463 * When decrypting, the tag value must be recomputed and compared with
464 * the received tag: if the two tag values differ, then either the tag
465 * or the encrypted data was altered in transit. As an alternative to
466 * this function, the `br_gcm_check_tag()` function can be used to
467 * compute and check the tag value.
468 *
469 * \param ctx GCM context structure.
470 * \param tag destination buffer for the tag (16 bytes).
471 */
472 void br_gcm_get_tag(br_gcm_context *ctx, void *tag);
473
474 /**
475 * \brief Compute and check GCM authentication tag.
476 *
477 * This function is an alternative to `br_gcm_get_tag()`, normally used
478 * on the receiving end (i.e. when decrypting value). The tag value is
479 * recomputed and compared with the provided tag value. If they match, 1
480 * is returned; on mismatch, 0 is returned. A returned value of 0 means
481 * that the data or the tag was altered in transit, normally leading to
482 * wholesale rejection of the complete message.
483 *
484 * \param ctx GCM context structure.
485 * \param tag tag value to compare with (16 bytes).
486 * \return 1 on success (exact match of tag value), 0 otherwise.
487 */
488 uint32_t br_gcm_check_tag(br_gcm_context *ctx, const void *tag);
489
490 /**
491 * \brief Compute GCM authentication tag (with truncation).
492 *
493 * This function is similar to `br_gcm_get_tag()`, except that it allows
494 * the tag to be truncated to a smaller length. The intended tag length
495 * is provided as `len` (in bytes); it MUST be no more than 16, but
496 * it may be smaller. Note that decreasing tag length mechanically makes
497 * forgeries easier; NIST SP 800-38D specifies that the tag length shall
498 * lie between 12 and 16 bytes (inclusive), but may be truncated down to
499 * 4 or 8 bytes, for specific applications that can tolerate it. It must
500 * also be noted that successful forgeries leak information on the
501 * authentication key, making subsequent forgeries easier. Therefore,
502 * tag truncation, and in particular truncation to sizes lower than 12
503 * bytes, shall be envisioned only with great care.
504 *
505 * The tag is written in the provided `tag` buffer. This call terminates
506 * the GCM run: no data may be processed with that GCM context
507 * afterwards, until `br_gcm_reset()` is called to initiate a new GCM
508 * run.
509 *
510 * The tag value must normally be sent along with the encrypted data.
511 * When decrypting, the tag value must be recomputed and compared with
512 * the received tag: if the two tag values differ, then either the tag
513 * or the encrypted data was altered in transit. As an alternative to
514 * this function, the `br_gcm_check_tag_trunc()` function can be used to
515 * compute and check the tag value.
516 *
517 * \param ctx GCM context structure.
518 * \param tag destination buffer for the tag.
519 * \param len tag length (16 bytes or less).
520 */
521 void br_gcm_get_tag_trunc(br_gcm_context *ctx, void *tag, size_t len);
522
523 /**
524 * \brief Compute and check GCM authentication tag (with truncation).
525 *
526 * This function is an alternative to `br_gcm_get_tag_trunc()`, normally used
527 * on the receiving end (i.e. when decrypting value). The tag value is
528 * recomputed and compared with the provided tag value. If they match, 1
529 * is returned; on mismatch, 0 is returned. A returned value of 0 means
530 * that the data or the tag was altered in transit, normally leading to
531 * wholesale rejection of the complete message.
532 *
533 * Tag length MUST be 16 bytes or less. The normal GCM tag length is 16
534 * bytes. See `br_check_tag_trunc()` for some discussion on the potential
535 * perils of truncating authentication tags.
536 *
537 * \param ctx GCM context structure.
538 * \param tag tag value to compare with.
539 * \param len tag length (in bytes).
540 * \return 1 on success (exact match of tag value), 0 otherwise.
541 */
542 uint32_t br_gcm_check_tag_trunc(br_gcm_context *ctx,
543 const void *tag, size_t len);
544
545 /**
546 * \brief Class instance for GCM.
547 */
548 extern const br_aead_class br_gcm_vtable;
549
550 /**
551 * \brief Context structure for EAX.
552 *
553 * EAX is an AEAD mode that combines a block cipher in CTR mode with
554 * CBC-MAC using the same block cipher and the same key, to provide
555 * authenticated encryption:
556 *
557 * - Any block cipher with 16-byte blocks can be used with EAX
558 * (technically, other block sizes are defined as well, but this
559 * is not implemented by these functions; shorter blocks also
560 * imply numerous security issues).
561 *
562 * - The nonce can have any length, as long as nonce values are
563 * not reused (thus, if nonces are randomly selected, the nonce
564 * size should be such that reuse probability is negligible).
565 *
566 * - Additional authenticated data length is unlimited.
567 *
568 * - Message length is unlimited.
569 *
570 * - The authentication tag has length 16 bytes.
571 *
572 * The EAX initialisation function receives as parameter an
573 * _initialised_ block cipher implementation context, with the secret
574 * key already set. A pointer to that context will be kept within the
575 * EAX context structure. It is up to the caller to allocate and
576 * initialise that block cipher context.
577 */
578 typedef struct {
579 /** \brief Pointer to vtable for this context. */
580 const br_aead_class *vtable;
581
582 #ifndef BR_DOXYGEN_IGNORE
583 const br_block_ctrcbc_class **bctx;
584 unsigned char L2[16];
585 unsigned char L4[16];
586 unsigned char nonce[16];
587 unsigned char head[16];
588 unsigned char ctr[16];
589 unsigned char cbcmac[16];
590 unsigned char buf[16];
591 size_t ptr;
592 #endif
593 } br_eax_context;
594
595 /**
596 * \brief EAX captured state.
597 *
598 * Some internal values computed by EAX may be captured at various
599 * points, and reused for another EAX run with the same secret key,
600 * for lower per-message overhead. Captured values do not depend on
601 * the nonce.
602 */
603 typedef struct {
604 #ifndef BR_DOXYGEN_IGNORE
605 unsigned char st[3][16];
606 #endif
607 } br_eax_state;
608
609 /**
610 * \brief Initialize an EAX context.
611 *
612 * A block cipher implementation, with its initialised context
613 * structure, is provided. The block cipher MUST use 16-byte blocks in
614 * CTR + CBC-MAC mode, and its secret key MUST have been already set in
615 * the provided context. The parameters are linked in the EAX context.
616 *
617 * After this function has been called, the `br_eax_reset()` function must
618 * be called, to provide the nonce for EAX computation.
619 *
620 * \param ctx EAX context structure.
621 * \param bctx block cipher context (already initialised with secret key).
622 */
623 void br_eax_init(br_eax_context *ctx, const br_block_ctrcbc_class **bctx);
624
625 /**
626 * \brief Capture pre-AAD state.
627 *
628 * This function precomputes key-dependent data, and stores it in the
629 * provided `st` structure. This structure should then be used with
630 * `br_eax_reset_pre_aad()`, or updated with `br_eax_get_aad_mac()`
631 * and then used with `br_eax_reset_post_aad()`.
632 *
633 * The EAX context structure is unmodified by this call.
634 *
635 * \param ctx EAX context structure.
636 * \param st recipient for captured state.
637 */
638 void br_eax_capture(const br_eax_context *ctx, br_eax_state *st);
639
640 /**
641 * \brief Reset an EAX context.
642 *
643 * This function resets an already initialised EAX context for a new
644 * computation run. Implementations and keys are conserved. This function
645 * can be called at any time; it cancels any ongoing EAX computation that
646 * uses the provided context structure.
647 *
648 * It is critical to EAX security that nonce values are not repeated for
649 * the same encryption key. Nonces can have arbitrary length. If nonces
650 * are randomly generated, then a nonce length of at least 128 bits (16
651 * bytes) is recommended, to make nonce reuse probability sufficiently
652 * low.
653 *
654 * \param ctx EAX context structure.
655 * \param nonce EAX nonce to use.
656 * \param len EAX nonce length (in bytes).
657 */
658 void br_eax_reset(br_eax_context *ctx, const void *nonce, size_t len);
659
660 /**
661 * \brief Reset an EAX context with a pre-AAD captured state.
662 *
663 * This function is an alternative to `br_eax_reset()`, that reuses a
664 * previously captured state structure for lower per-message overhead.
665 * The state should have been populated with `br_eax_capture_state()`
666 * but not updated with `br_eax_get_aad_mac()`.
667 *
668 * After this function is called, additional authenticated data MUST
669 * be injected. At least one byte of additional authenticated data
670 * MUST be provided with `br_eax_aad_inject()`; computation result will
671 * be incorrect if `br_eax_flip()` is called right away.
672 *
673 * After injection of the AAD and call to `br_eax_flip()`, at least
674 * one message byte must be provided. Empty messages are not supported
675 * with this reset mode.
676 *
677 * \param ctx EAX context structure.
678 * \param st pre-AAD captured state.
679 * \param nonce EAX nonce to use.
680 * \param len EAX nonce length (in bytes).
681 */
682 void br_eax_reset_pre_aad(br_eax_context *ctx, const br_eax_state *st,
683 const void *nonce, size_t len);
684
685 /**
686 * \brief Reset an EAX context with a post-AAD captured state.
687 *
688 * This function is an alternative to `br_eax_reset()`, that reuses a
689 * previously captured state structure for lower per-message overhead.
690 * The state should have been populated with `br_eax_capture_state()`
691 * and then updated with `br_eax_get_aad_mac()`.
692 *
693 * After this function is called, message data MUST be injected. The
694 * `br_eax_flip()` function MUST NOT be called. At least one byte of
695 * message data MUST be provided with `br_eax_run()`; empty messages
696 * are not supported with this reset mode.
697 *
698 * \param ctx EAX context structure.
699 * \param st post-AAD captured state.
700 * \param nonce EAX nonce to use.
701 * \param len EAX nonce length (in bytes).
702 */
703 void br_eax_reset_post_aad(br_eax_context *ctx, const br_eax_state *st,
704 const void *nonce, size_t len);
705
706 /**
707 * \brief Inject additional authenticated data into EAX.
708 *
709 * The provided data is injected into a running EAX computation. Additional
710 * data must be injected _before_ the call to `br_eax_flip()`.
711 * Additional data can be injected in several chunks of arbitrary length;
712 * the total amount of additional authenticated data is unlimited.
713 *
714 * \param ctx EAX context structure.
715 * \param data pointer to additional authenticated data.
716 * \param len length of additional authenticated data (in bytes).
717 */
718 void br_eax_aad_inject(br_eax_context *ctx, const void *data, size_t len);
719
720 /**
721 * \brief Finish injection of additional authenticated data into EAX.
722 *
723 * This function MUST be called before beginning the actual encryption
724 * or decryption (with `br_eax_run()`), even if no additional authenticated
725 * data was injected. No additional authenticated data may be injected
726 * after this function call.
727 *
728 * \param ctx EAX context structure.
729 */
730 void br_eax_flip(br_eax_context *ctx);
731
732 /**
733 * \brief Obtain a copy of the MAC on additional authenticated data.
734 *
735 * This function may be called only after `br_eax_flip()`; it copies the
736 * AAD-specific MAC value into the provided state. The MAC value depends
737 * on the secret key and the additional data itself, but not on the
738 * nonce. The updated state `st` is meant to be used as parameter for a
739 * further `br_eax_reset_post_aad()` call.
740 *
741 * \param ctx EAX context structure.
742 * \param st captured state to update.
743 */
744 static inline void
745 br_eax_get_aad_mac(const br_eax_context *ctx, br_eax_state *st)
746 {
747 memcpy(st->st[1], ctx->head, sizeof ctx->head);
748 }
749
750 /**
751 * \brief Encrypt or decrypt some data with EAX.
752 *
753 * Data encryption or decryption can be done after `br_eax_flip()`
754 * has been called on the context. If `encrypt` is non-zero, then the
755 * provided data shall be plaintext, and it is encrypted in place.
756 * Otherwise, the data shall be ciphertext, and it is decrypted in place.
757 *
758 * Data may be provided in several chunks of arbitrary length.
759 *
760 * \param ctx EAX context structure.
761 * \param encrypt non-zero for encryption, zero for decryption.
762 * \param data data to encrypt or decrypt.
763 * \param len data length (in bytes).
764 */
765 void br_eax_run(br_eax_context *ctx, int encrypt, void *data, size_t len);
766
767 /**
768 * \brief Compute EAX authentication tag.
769 *
770 * Compute the EAX authentication tag. The tag is a 16-byte value which
771 * is written in the provided `tag` buffer. This call terminates the
772 * EAX run: no data may be processed with that EAX context afterwards,
773 * until `br_eax_reset()` is called to initiate a new EAX run.
774 *
775 * The tag value must normally be sent along with the encrypted data.
776 * When decrypting, the tag value must be recomputed and compared with
777 * the received tag: if the two tag values differ, then either the tag
778 * or the encrypted data was altered in transit. As an alternative to
779 * this function, the `br_eax_check_tag()` function can be used to
780 * compute and check the tag value.
781 *
782 * \param ctx EAX context structure.
783 * \param tag destination buffer for the tag (16 bytes).
784 */
785 void br_eax_get_tag(br_eax_context *ctx, void *tag);
786
787 /**
788 * \brief Compute and check EAX authentication tag.
789 *
790 * This function is an alternative to `br_eax_get_tag()`, normally used
791 * on the receiving end (i.e. when decrypting value). The tag value is
792 * recomputed and compared with the provided tag value. If they match, 1
793 * is returned; on mismatch, 0 is returned. A returned value of 0 means
794 * that the data or the tag was altered in transit, normally leading to
795 * wholesale rejection of the complete message.
796 *
797 * \param ctx EAX context structure.
798 * \param tag tag value to compare with (16 bytes).
799 * \return 1 on success (exact match of tag value), 0 otherwise.
800 */
801 uint32_t br_eax_check_tag(br_eax_context *ctx, const void *tag);
802
803 /**
804 * \brief Compute EAX authentication tag (with truncation).
805 *
806 * This function is similar to `br_eax_get_tag()`, except that it allows
807 * the tag to be truncated to a smaller length. The intended tag length
808 * is provided as `len` (in bytes); it MUST be no more than 16, but
809 * it may be smaller. Note that decreasing tag length mechanically makes
810 * forgeries easier; NIST SP 800-38D specifies that the tag length shall
811 * lie between 12 and 16 bytes (inclusive), but may be truncated down to
812 * 4 or 8 bytes, for specific applications that can tolerate it. It must
813 * also be noted that successful forgeries leak information on the
814 * authentication key, making subsequent forgeries easier. Therefore,
815 * tag truncation, and in particular truncation to sizes lower than 12
816 * bytes, shall be envisioned only with great care.
817 *
818 * The tag is written in the provided `tag` buffer. This call terminates
819 * the EAX run: no data may be processed with that EAX context
820 * afterwards, until `br_eax_reset()` is called to initiate a new EAX
821 * run.
822 *
823 * The tag value must normally be sent along with the encrypted data.
824 * When decrypting, the tag value must be recomputed and compared with
825 * the received tag: if the two tag values differ, then either the tag
826 * or the encrypted data was altered in transit. As an alternative to
827 * this function, the `br_eax_check_tag_trunc()` function can be used to
828 * compute and check the tag value.
829 *
830 * \param ctx EAX context structure.
831 * \param tag destination buffer for the tag.
832 * \param len tag length (16 bytes or less).
833 */
834 void br_eax_get_tag_trunc(br_eax_context *ctx, void *tag, size_t len);
835
836 /**
837 * \brief Compute and check EAX authentication tag (with truncation).
838 *
839 * This function is an alternative to `br_eax_get_tag_trunc()`, normally used
840 * on the receiving end (i.e. when decrypting value). The tag value is
841 * recomputed and compared with the provided tag value. If they match, 1
842 * is returned; on mismatch, 0 is returned. A returned value of 0 means
843 * that the data or the tag was altered in transit, normally leading to
844 * wholesale rejection of the complete message.
845 *
846 * Tag length MUST be 16 bytes or less. The normal EAX tag length is 16
847 * bytes. See `br_check_tag_trunc()` for some discussion on the potential
848 * perils of truncating authentication tags.
849 *
850 * \param ctx EAX context structure.
851 * \param tag tag value to compare with.
852 * \param len tag length (in bytes).
853 * \return 1 on success (exact match of tag value), 0 otherwise.
854 */
855 uint32_t br_eax_check_tag_trunc(br_eax_context *ctx,
856 const void *tag, size_t len);
857
858 /**
859 * \brief Class instance for EAX.
860 */
861 extern const br_aead_class br_eax_vtable;
862
863 /**
864 * \brief Context structure for CCM.
865 *
866 * CCM is an AEAD mode that combines a block cipher in CTR mode with
867 * CBC-MAC using the same block cipher and the same key, to provide
868 * authenticated encryption:
869 *
870 * - Any block cipher with 16-byte blocks can be used with CCM
871 * (technically, other block sizes are defined as well, but this
872 * is not implemented by these functions; shorter blocks also
873 * imply numerous security issues).
874 *
875 * - The authentication tag length, and plaintext length, MUST be
876 * known when starting processing data. Plaintext and ciphertext
877 * can still be provided by chunks, but the total size must match
878 * the value provided upon initialisation.
879 *
880 * - The nonce length is constrained between 7 and 13 bytes (inclusive).
881 * Furthermore, the plaintext length, when encoded, must fit over
882 * 15-nonceLen bytes; thus, if the nonce has length 13 bytes, then
883 * the plaintext length cannot exceed 65535 bytes.
884 *
885 * - Additional authenticated data length is practically unlimited
886 * (formal limit is at 2^64 bytes).
887 *
888 * - The authentication tag has length 4 to 16 bytes (even values only).
889 *
890 * The CCM initialisation function receives as parameter an
891 * _initialised_ block cipher implementation context, with the secret
892 * key already set. A pointer to that context will be kept within the
893 * CCM context structure. It is up to the caller to allocate and
894 * initialise that block cipher context.
895 */
896 typedef struct {
897 #ifndef BR_DOXYGEN_IGNORE
898 const br_block_ctrcbc_class **bctx;
899 unsigned char ctr[16];
900 unsigned char cbcmac[16];
901 unsigned char tagmask[16];
902 unsigned char buf[16];
903 size_t ptr;
904 size_t tag_len;
905 #endif
906 } br_ccm_context;
907
908 /**
909 * \brief Initialize a CCM context.
910 *
911 * A block cipher implementation, with its initialised context
912 * structure, is provided. The block cipher MUST use 16-byte blocks in
913 * CTR + CBC-MAC mode, and its secret key MUST have been already set in
914 * the provided context. The parameters are linked in the CCM context.
915 *
916 * After this function has been called, the `br_ccm_reset()` function must
917 * be called, to provide the nonce for CCM computation.
918 *
919 * \param ctx CCM context structure.
920 * \param bctx block cipher context (already initialised with secret key).
921 */
922 void br_ccm_init(br_ccm_context *ctx, const br_block_ctrcbc_class **bctx);
923
924 /**
925 * \brief Reset a CCM context.
926 *
927 * This function resets an already initialised CCM context for a new
928 * computation run. Implementations and keys are conserved. This function
929 * can be called at any time; it cancels any ongoing CCM computation that
930 * uses the provided context structure.
931 *
932 * The `aad_len` parameter contains the total length, in bytes, of the
933 * additional authenticated data. It may be zero. That length MUST be
934 * exact.
935 *
936 * The `data_len` parameter contains the total length, in bytes, of the
937 * data that will be injected (plaintext or ciphertext). That length MUST
938 * be exact. Moreover, that length MUST be less than 2^(8*(15-nonce_len)).
939 *
940 * The nonce length (`nonce_len`), in bytes, must be in the 7..13 range
941 * (inclusive).
942 *
943 * The tag length (`tag_len`), in bytes, must be in the 4..16 range, and
944 * be an even integer. Short tags mechanically allow for higher forgery
945 * probabilities; hence, tag sizes smaller than 12 bytes shall be used only
946 * with care.
947 *
948 * It is critical to CCM security that nonce values are not repeated for
949 * the same encryption key. Random generation of nonces is not generally
950 * recommended, due to the relatively small maximum nonce value.
951 *
952 * Returned value is 1 on success, 0 on error. An error is reported if
953 * the tag or nonce length is out of range, or if the
954 * plaintext/ciphertext length cannot be encoded with the specified
955 * nonce length.
956 *
957 * \param ctx CCM context structure.
958 * \param nonce CCM nonce to use.
959 * \param nonce_len CCM nonce length (in bytes, 7 to 13).
960 * \param aad_len additional authenticated data length (in bytes).
961 * \param data_len plaintext/ciphertext length (in bytes).
962 * \param tag_len tag length (in bytes).
963 * \return 1 on success, 0 on error.
964 */
965 int br_ccm_reset(br_ccm_context *ctx, const void *nonce, size_t nonce_len,
966 uint64_t aad_len, uint64_t data_len, size_t tag_len);
967
968 /**
969 * \brief Inject additional authenticated data into CCM.
970 *
971 * The provided data is injected into a running CCM computation. Additional
972 * data must be injected _before_ the call to `br_ccm_flip()`.
973 * Additional data can be injected in several chunks of arbitrary length,
974 * but the total amount MUST exactly match the value which was provided
975 * to `br_ccm_reset()`.
976 *
977 * \param ctx CCM context structure.
978 * \param data pointer to additional authenticated data.
979 * \param len length of additional authenticated data (in bytes).
980 */
981 void br_ccm_aad_inject(br_ccm_context *ctx, const void *data, size_t len);
982
983 /**
984 * \brief Finish injection of additional authenticated data into CCM.
985 *
986 * This function MUST be called before beginning the actual encryption
987 * or decryption (with `br_ccm_run()`), even if no additional authenticated
988 * data was injected. No additional authenticated data may be injected
989 * after this function call.
990 *
991 * \param ctx CCM context structure.
992 */
993 void br_ccm_flip(br_ccm_context *ctx);
994
995 /**
996 * \brief Encrypt or decrypt some data with CCM.
997 *
998 * Data encryption or decryption can be done after `br_ccm_flip()`
999 * has been called on the context. If `encrypt` is non-zero, then the
1000 * provided data shall be plaintext, and it is encrypted in place.
1001 * Otherwise, the data shall be ciphertext, and it is decrypted in place.
1002 *
1003 * Data may be provided in several chunks of arbitrary length, provided
1004 * that the total length exactly matches the length provided to the
1005 * `br_ccm_reset()` call.
1006 *
1007 * \param ctx CCM context structure.
1008 * \param encrypt non-zero for encryption, zero for decryption.
1009 * \param data data to encrypt or decrypt.
1010 * \param len data length (in bytes).
1011 */
1012 void br_ccm_run(br_ccm_context *ctx, int encrypt, void *data, size_t len);
1013
1014 /**
1015 * \brief Compute CCM authentication tag.
1016 *
1017 * Compute the CCM authentication tag. This call terminates the CCM
1018 * run: all data must have been injected with `br_ccm_run()` (in zero,
1019 * one or more successive calls). After this function has been called,
1020 * no more data can br processed; a `br_ccm_reset()` call is required
1021 * to start a new message.
1022 *
1023 * The tag length was provided upon context initialisation (last call
1024 * to `br_ccm_reset()`); it is returned by this function.
1025 *
1026 * The tag value must normally be sent along with the encrypted data.
1027 * When decrypting, the tag value must be recomputed and compared with
1028 * the received tag: if the two tag values differ, then either the tag
1029 * or the encrypted data was altered in transit. As an alternative to
1030 * this function, the `br_ccm_check_tag()` function can be used to
1031 * compute and check the tag value.
1032 *
1033 * \param ctx CCM context structure.
1034 * \param tag destination buffer for the tag (up to 16 bytes).
1035 * \return the tag length (in bytes).
1036 */
1037 size_t br_ccm_get_tag(br_ccm_context *ctx, void *tag);
1038
1039 /**
1040 * \brief Compute and check CCM authentication tag.
1041 *
1042 * This function is an alternative to `br_ccm_get_tag()`, normally used
1043 * on the receiving end (i.e. when decrypting value). The tag value is
1044 * recomputed and compared with the provided tag value. If they match, 1
1045 * is returned; on mismatch, 0 is returned. A returned value of 0 means
1046 * that the data or the tag was altered in transit, normally leading to
1047 * wholesale rejection of the complete message.
1048 *
1049 * \param ctx CCM context structure.
1050 * \param tag tag value to compare with (up to 16 bytes).
1051 * \return 1 on success (exact match of tag value), 0 otherwise.
1052 */
1053 uint32_t br_ccm_check_tag(br_ccm_context *ctx, const void *tag);
1054
1055 #ifdef __cplusplus
1056 }
1057 #endif
1058
1059 #endif