2 * Copyright (c) 2017 Thomas Pornin <pornin@bolet.org>
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:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
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
25 #ifndef BR_BEARSSL_AEAD_H__
26 #define BR_BEARSSL_AEAD_H__
31 #include "bearssl_block.h"
32 #include "bearssl_hash.h"
38 /** \file bearssl_aead.h
40 * # Authenticated Encryption with Additional Data
42 * This file documents the API for AEAD encryption.
47 * An AEAD algorithm processes messages and provides confidentiality
48 * (encryption) and checked integrity (MAC). It uses the following
51 * - A symmetric key. Exact size depends on the AEAD algorithm.
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
58 * - Data to encrypt and protect.
60 * - Additional authenticated data, which is covered by the MAC but
61 * otherwise left untouched (i.e. not encrypted).
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
74 * For each AEAD algorithm, identified by a symbolic name (hereafter
75 * denoted as "`xxx`"), the following functions are defined:
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
87 * Start a new AEAD computation. The nonce value is provided as
88 * parameter to this function.
90 * - `br_xxx_aad_inject()`
92 * Inject some additional authenticated data. Additional data may
93 * be provided in several chunks of arbitrary length.
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).
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.
107 * - `br_xxx_get_tag()`
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.
114 * - `br_xxx_check_tag()`
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.
120 * This API makes the following assumptions on the AEAD algorithm:
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.
125 * - The additional authenticated data must be processed first,
126 * before the encrypted/decrypted data.
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 lengh in bits is not a multiple of 8.
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
139 * ## Object-Oriented API
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
148 * Pointer to the reset function, that allows starting a new
153 * Pointer to the additional authenticated data injection function.
157 * Pointer to the function that transitions from additional data
158 * to main message data processing.
162 * Pointer to the function that computes and returns the tag.
166 * Pointer to the function that computes and verifies the tag against
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.
175 * \brief Class type of an AEAD algorithm.
177 typedef struct br_aead_class_ br_aead_class
;
178 struct br_aead_class_
{
181 * \brief Size (in bytes) of authentication tags created by
182 * this AEAD algorithm.
187 * \brief Reset an AEAD context.
189 * This function resets an already initialised AEAD context for
190 * a new computation run. Implementations and keys are
191 * conserved. This function can be called at any time; it
192 * cancels any ongoing AEAD computation that uses the provided
195 * The provided IV is a _nonce_. Each AEAD algorithm has its
196 * own requirements on IV size and contents; for most of them,
197 * it is crucial to security that each nonce value is used
198 * only once for a given secret key.
200 * \param cc AEAD context structure.
201 * \param iv AEAD nonce to use.
202 * \param len AEAD nonce length (in bytes).
204 void (*reset
)(const br_aead_class
**cc
, const void *iv
, size_t len
);
207 * \brief Inject additional authenticated data.
209 * The provided data is injected into a running AEAD
210 * computation. Additional data must be injected _before_ the
211 * call to `flip()`. Additional data can be injected in several
212 * chunks of arbitrary length.
214 * \param cc AEAD context structure.
215 * \param data pointer to additional authenticated data.
216 * \param len length of additiona authenticated data (in bytes).
218 void (*aad_inject
)(const br_aead_class
**cc
,
219 const void *data
, size_t len
);
222 * \brief Finish injection of additional authenticated data.
224 * This function MUST be called before beginning the actual
225 * encryption or decryption (with `run()`), even if no
226 * additional authenticated data was injected. No additional
227 * authenticated data may be injected after this function call.
229 * \param cc AEAD context structure.
231 void (*flip
)(const br_aead_class
**cc
);
234 * \brief Encrypt or decrypt some data.
236 * Data encryption or decryption can be done after `flip()` has
237 * been called on the context. If `encrypt` is non-zero, then
238 * the provided data shall be plaintext, and it is encrypted in
239 * place. Otherwise, the data shall be ciphertext, and it is
240 * decrypted in place.
242 * Data may be provided in several chunks of arbitrary length.
244 * \param cc AEAD context structure.
245 * \param encrypt non-zero for encryption, zero for decryption.
246 * \param data data to encrypt or decrypt.
247 * \param len data length (in bytes).
249 void (*run
)(const br_aead_class
**cc
, int encrypt
,
250 void *data
, size_t len
);
253 * \brief Compute authentication tag.
255 * Compute the AEAD authentication tag. The tag length depends
256 * on the AEAD algorithm; it is written in the provided `tag`
257 * buffer. This call terminates the AEAD run: no data may be
258 * processed with that AEAD context afterwards, until `reset()`
259 * is called to initiate a new AEAD run.
261 * The tag value must normally be sent along with the encrypted
262 * data. When decrypting, the tag value must be recomputed and
263 * compared with the received tag: if the two tag values differ,
264 * then either the tag or the encrypted data was altered in
265 * transit. As an alternative to this function, the
266 * `check_tag()` function may be used to compute and check the
269 * \param cc AEAD context structure.
270 * \param tag destination buffer for the tag.
272 void (*get_tag
)(const br_aead_class
**cc
, void *tag
);
275 * \brief Compute and check authentication tag.
277 * This function is an alternative to `get_tag()`, and is
278 * normally used on the receiving end (i.e. when decrypting
279 * messages). The tag value is recomputed and compared with the
280 * provided tag value. If they match, 1 is returned; on
281 * mismatch, 0 is returned. A returned value of 0 means that the
282 * data or the tag was altered in transit, normally leading to
283 * wholesale rejection of the complete message.
285 * \param cc AEAD context structure.
286 * \param tag tag value to compare with (16 bytes).
287 * \return 1 on success (exact match of tag value), 0 otherwise.
289 uint32_t (*check_tag
)(const br_aead_class
**cc
, const void *tag
);
293 * \brief Context structure for GCM.
295 * GCM is an AEAD mode that combines a block cipher in CTR mode with a
296 * MAC based on GHASH, to provide authenticated encryption:
298 * - Any block cipher with 16-byte blocks can be used with GCM.
300 * - The nonce can have any length, from 0 up to 2^64-1 bits; however,
301 * 96-bit nonces (12 bytes) are recommended (nonces with a length
302 * distinct from 12 bytes are internally hashed, which risks reusing
303 * nonce value with a small but not always negligible probability).
305 * - Additional authenticated data may have length up to 2^64-1 bits.
307 * - Message length may range up to 2^39-256 bits at most.
309 * - The authentication tag has length 16 bytes.
311 * The GCM initialisation function receives as parameter an
312 * _initialised_ block cipher implementation context, with the secret
313 * key already set. A pointer to that context will be kept within the
314 * GCM context structure. It is up to the caller to allocate and
315 * initialise that block cipher context.
318 /** \brief Pointer to vtable for this context. */
319 const br_aead_class
*vtable
;
321 #ifndef BR_DOXYGEN_IGNORE
322 const br_block_ctr_class
**bctx
;
325 unsigned char j0_1
[12];
326 unsigned char buf
[16];
329 uint64_t count_aad
, count_ctr
;
334 * \brief Initialize a GCM context.
336 * A block cipher implementation, with its initialised context structure,
337 * is provided. The block cipher MUST use 16-byte blocks in CTR mode,
338 * and its secret key MUST have been already set in the provided context.
339 * A GHASH implementation must also be provided. The parameters are linked
340 * in the GCM context.
342 * After this function has been called, the `br_gcm_reset()` function must
343 * be called, to provide the IV for GCM computation.
345 * \param ctx GCM context structure.
346 * \param bctx block cipher context (already initialised with secret key).
347 * \param gh GHASH implementation.
349 void br_gcm_init(br_gcm_context
*ctx
,
350 const br_block_ctr_class
**bctx
, br_ghash gh
);
353 * \brief Reset a GCM context.
355 * This function resets an already initialised GCM context for a new
356 * computation run. Implementations and keys are conserved. This function
357 * can be called at any time; it cancels any ongoing GCM computation that
358 * uses the provided context structure.
360 * The provided IV is a _nonce_. It is critical to GCM security that IV
361 * values are not repeated for the same encryption key. IV can have
362 * arbitrary length (up to 2^64-1 bits), but the "normal" length is
363 * 96 bits (12 bytes).
365 * \param ctx GCM context structure.
366 * \param iv GCM nonce to use.
367 * \param len GCM nonce length (in bytes).
369 void br_gcm_reset(br_gcm_context
*ctx
, const void *iv
, size_t len
);
372 * \brief Inject additional authenticated data into GCM.
374 * The provided data is injected into a running GCM computation. Additional
375 * data must be injected _before_ the call to `br_gcm_flip()`.
376 * Additional data can be injected in several chunks of arbitrary length;
377 * the maximum total size of additional authenticated data is 2^64-1
380 * \param ctx GCM context structure.
381 * \param data pointer to additional authenticated data.
382 * \param len length of additiona authenticated data (in bytes).
384 void br_gcm_aad_inject(br_gcm_context
*ctx
, const void *data
, size_t len
);
387 * \brief Finish injection of additional authenticated data into GCM.
389 * This function MUST be called before beginning the actual encryption
390 * or decryption (with `br_gcm_run()`), even if no additional authenticated
391 * data was injected. No additional authenticated data may be injected
392 * after this function call.
394 * \param ctx GCM context structure.
396 void br_gcm_flip(br_gcm_context
*ctx
);
399 * \brief Encrypt or decrypt some data with GCM.
401 * Data encryption or decryption can be done after `br_gcm_flip()`
402 * has been called on the context. If `encrypt` is non-zero, then the
403 * provided data shall be plaintext, and it is encrypted in place.
404 * Otherwise, the data shall be ciphertext, and it is decrypted in place.
406 * Data may be provided in several chunks of arbitrary length. The maximum
407 * total length for data is 2^39-256 bits, i.e. about 65 gigabytes.
409 * \param ctx GCM context structure.
410 * \param encrypt non-zero for encryption, zero for decryption.
411 * \param data data to encrypt or decrypt.
412 * \param len data length (in bytes).
414 void br_gcm_run(br_gcm_context
*ctx
, int encrypt
, void *data
, size_t len
);
417 * \brief Compute GCM authentication tag.
419 * Compute the GCM authentication tag. The tag is a 16-byte value which
420 * is written in the provided `tag` buffer. This call terminates the
421 * GCM run: no data may be processed with that GCM context afterwards,
422 * until `br_gcm_reset()` is called to initiate a new GCM run.
424 * The tag value must normally be sent along with the encrypted data.
425 * When decrypting, the tag value must be recomputed and compared with
426 * the received tag: if the two tag values differ, then either the tag
427 * or the encrypted data was altered in transit. As an alternative to
428 * this function, the `br_gcm_check_tag()` function can be used to
429 * compute and check the tag value.
431 * \param ctx GCM context structure.
432 * \param tag destination buffer for the tag (16 bytes).
434 void br_gcm_get_tag(br_gcm_context
*ctx
, void *tag
);
437 * \brief Compute and check GCM authentication tag.
439 * This function is an alternative to `br_gcm_get_tag()`, normally used
440 * on the receiving end (i.e. when decrypting value). The tag value is
441 * recomputed and compared with the provided tag value. If they match, 1
442 * is returned; on mismatch, 0 is returned. A returned value of 0 means
443 * that the data or the tag was altered in transit, normally leading to
444 * wholesale rejection of the complete message.
446 * \param ctx GCM context structure.
447 * \param tag tag value to compare with (16 bytes).
448 * \return 1 on success (exact match of tag value), 0 otherwise.
450 uint32_t br_gcm_check_tag(br_gcm_context
*ctx
, const void *tag
);
453 * \brief Class instance for GCM.
455 extern const br_aead_class br_gcm_vtable
;