Coverage Report

Created: 2024-11-21 06:38

/src/BearSSL/inc/bearssl_aead.h
Line
Count
Source (jump to first uncovered line)
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
0
{
747
0
  memcpy(st->st[1], ctx->head, sizeof ctx->head);
748
0
}
Unexecuted instantiation: module.cpp:br_eax_get_aad_mac(br_eax_context const*, br_eax_state*)
Unexecuted instantiation: poly1305_ctmul.c:br_eax_get_aad_mac
Unexecuted instantiation: chacha20_sse2.c:br_eax_get_aad_mac
Unexecuted instantiation: chacha20_ct.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_x86ni_ctrcbc.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_x86ni.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_small_ctrcbc.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_ct_ctrcbc.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_ct_ctr.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_ct64_ctrcbc.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_ct64.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_ct.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_common.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_big_ctrcbc.c:br_eax_get_aad_mac
Unexecuted instantiation: prf_md5sha1.c:br_eax_get_aad_mac
Unexecuted instantiation: prf.c:br_eax_get_aad_mac
Unexecuted instantiation: sysrng.c:br_eax_get_aad_mac
Unexecuted instantiation: hmac_drbg.c:br_eax_get_aad_mac
Unexecuted instantiation: hmac.c:br_eax_get_aad_mac
Unexecuted instantiation: shake.c:br_eax_get_aad_mac
Unexecuted instantiation: hkdf.c:br_eax_get_aad_mac
Unexecuted instantiation: sha2small.c:br_eax_get_aad_mac
Unexecuted instantiation: sha2big.c:br_eax_get_aad_mac
Unexecuted instantiation: sha1.c:br_eax_get_aad_mac
Unexecuted instantiation: md5sha1.c:br_eax_get_aad_mac
Unexecuted instantiation: md5.c:br_eax_get_aad_mac
Unexecuted instantiation: ghash_ctmul32.c:br_eax_get_aad_mac
Unexecuted instantiation: ecdsa_i31_vrfy_raw.c:br_eax_get_aad_mac
Unexecuted instantiation: ecdsa_i31_sign_raw.c:br_eax_get_aad_mac
Unexecuted instantiation: ecdsa_i31_bits.c:br_eax_get_aad_mac
Unexecuted instantiation: ecdsa_i15_vrfy_raw.c:br_eax_get_aad_mac
Unexecuted instantiation: ecdsa_i15_sign_raw.c:br_eax_get_aad_mac
Unexecuted instantiation: ecdsa_i15_bits.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_secp521r1.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_secp384r1.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_secp256r1.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_pubkey.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_prime_i31.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_prime_i15.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_p256_m64.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_p256_m62.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_p256_m31.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_p256_m15.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_keygen.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_default.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_c25519_m64.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_c25519_m62.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_c25519_m31.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_c25519_m15.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_c25519_i31.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_c25519_i15.c:br_eax_get_aad_mac
Unexecuted instantiation: ec_all_m31.c:br_eax_get_aad_mac
Unexecuted instantiation: enc64be.c:br_eax_get_aad_mac
Unexecuted instantiation: enc32le.c:br_eax_get_aad_mac
Unexecuted instantiation: enc32be.c:br_eax_get_aad_mac
Unexecuted instantiation: dec64be.c:br_eax_get_aad_mac
Unexecuted instantiation: dec32le.c:br_eax_get_aad_mac
Unexecuted instantiation: dec32be.c:br_eax_get_aad_mac
Unexecuted instantiation: ccopy.c:br_eax_get_aad_mac
Unexecuted instantiation: gcm.c:br_eax_get_aad_mac
Unexecuted instantiation: ccm.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_small_enc.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_ct_enc.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_ct64_enc.c:br_eax_get_aad_mac
Unexecuted instantiation: aes_big_enc.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_sub.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_rshift.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_ninv31.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_montmul.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_modpow.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_iszero.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_fmont.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_encode.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_decode.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_decmod.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_bitlen.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_add.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_sub.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_rshift.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_ninv15.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_montmul.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_modpow.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_iszero.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_fmont.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_encode.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_decode.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_decmod.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_bitlen.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_add.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_tmont.c:br_eax_get_aad_mac
Unexecuted instantiation: i31_muladd.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_tmont.c:br_eax_get_aad_mac
Unexecuted instantiation: i15_muladd.c:br_eax_get_aad_mac
Unexecuted instantiation: i32_div32.c:br_eax_get_aad_mac
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