/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 |