BearSSL

Data Structures | Functions | Variables
bearssl_aead.h File Reference
Include dependency graph for bearssl_aead.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures
struct | br_aead_class
| Class type of an AEAD algorithm. More...
struct | br_gcm_context
| Context structure for GCM. More...
struct | br_eax_context
| Context structure for EAX. More...
struct | br_eax_state
| EAX captured state. More...
struct | br_ccm_context
| Context structure for CCM. More...

## Functions
void | br_gcm_init (br_gcm_context *ctx, const br_block_ctr_class **bctx, br_ghash gh)
| Initialize a GCM context. More...
void | br_gcm_reset (br_gcm_context *ctx, const void *iv, size_t len)
| Reset a GCM context. More...
void | br_gcm_aad_inject (br_gcm_context *ctx, const void *data, size_t len)
| Inject additional authenticated data into GCM. More...
void | br_gcm_flip (br_gcm_context *ctx)
| Finish injection of additional authenticated data into GCM. More...
void | br_gcm_run (br_gcm_context *ctx, int encrypt, void *data, size_t len)
| Encrypt or decrypt some data with GCM. More...
void | br_gcm_get_tag (br_gcm_context *ctx, void *tag)
| Compute GCM authentication tag. More...
uint32_t | br_gcm_check_tag (br_gcm_context *ctx, const void *tag)
| Compute and check GCM authentication tag. More...
void | br_gcm_get_tag_trunc (br_gcm_context *ctx, void *tag, size_t len)
| Compute GCM authentication tag (with truncation). More...
uint32_t | br_gcm_check_tag_trunc (br_gcm_context *ctx, const void *tag, size_t len)
| Compute and check GCM authentication tag (with truncation). More...
void | br_eax_init (br_eax_context *ctx, const br_block_ctrcbc_class **bctx)
| Initialize an EAX context. More...
void | br_eax_capture (const br_eax_context *ctx, br_eax_state *st)
| Capture pre-AAD state. More...
void | br_eax_reset (br_eax_context *ctx, const void *nonce, size_t len)
| Reset an EAX context. More...
void | br_eax_reset_pre_aad (br_eax_context *ctx, const br_eax_state *st, const void *nonce, size_t len)
| Reset an EAX context with a pre-AAD captured state. More...
void | br_eax_reset_post_aad (br_eax_context *ctx, const br_eax_state *st, const void *nonce, size_t len)
| Reset an EAX context with a post-AAD captured state. More...
void | br_eax_aad_inject (br_eax_context *ctx, const void *data, size_t len)
| Inject additional authenticated data into EAX. More...
void | br_eax_flip (br_eax_context *ctx)
| Finish injection of additional authenticated data into EAX. More...
static void | br_eax_get_aad_mac (const br_eax_context *ctx, br_eax_state *st)
| Obtain a copy of the MAC on additional authenticated data. More...
void | br_eax_run (br_eax_context *ctx, int encrypt, void *data, size_t len)
| Encrypt or decrypt some data with EAX. More...
void | br_eax_get_tag (br_eax_context *ctx, void *tag)
| Compute EAX authentication tag. More...
uint32_t | br_eax_check_tag (br_eax_context *ctx, const void *tag)
| Compute and check EAX authentication tag. More...
void | br_eax_get_tag_trunc (br_eax_context *ctx, void *tag, size_t len)
| Compute EAX authentication tag (with truncation). More...
uint32_t | br_eax_check_tag_trunc (br_eax_context *ctx, const void *tag, size_t len)
| Compute and check EAX authentication tag (with truncation). More...
void | br_ccm_init (br_ccm_context *ctx, const br_block_ctrcbc_class **bctx)
| Initialize a CCM context. More...
int | br_ccm_reset (br_ccm_context *ctx, const void *nonce, size_t nonce_len, uint64_t aad_len, uint64_t data_len, size_t tag_len)
| Reset a CCM context. More...
void | br_ccm_aad_inject (br_ccm_context *ctx, const void *data, size_t len)
| Inject additional authenticated data into CCM. More...
void | br_ccm_flip (br_ccm_context *ctx)
| Finish injection of additional authenticated data into CCM. More...
void | br_ccm_run (br_ccm_context *ctx, int encrypt, void *data, size_t len)
| Encrypt or decrypt some data with CCM. More...
size_t | br_ccm_get_tag (br_ccm_context *ctx, void *tag)
| Compute CCM authentication tag. More...
uint32_t | br_ccm_check_tag (br_ccm_context *ctx, const void *tag)
| Compute and check CCM authentication tag. More...

## Variables
const br_aead_class | br_gcm_vtable
| Class instance for GCM. More...
const br_aead_class | br_eax_vtable
| Class instance for EAX. More...

## Detailed Description

# Authenticated Encryption with Additional Data

This file documents the API for AEAD encryption.

## Procedural API

An AEAD algorithm processes messages and provides confidentiality (encryption) and checked integrity (MAC). It uses the following parameters:

- A symmetric key. Exact size depends on the AEAD algorithm.
- A nonce (IV). Size depends on the AEAD algorithm; for most algorithms, it is crucial for security that any given nonce value is never used twice for the same key and distinct messages.
- Data to encrypt and protect.
- Additional authenticated data, which is covered by the MAC but otherwise left untouched (i.e. not encrypted).

The AEAD algorithm encrypts the data, and produces an authentication tag. It is assumed that the encrypted data, the tag, the additional authenticated data and the nonce are sent to the receiver; the additional data and the nonce may be implicit (e.g. using elements of the underlying transport protocol, such as record sequence numbers). The receiver will recompute the tag value and compare it with the one received; if they match, then the data is correct, and can be decrypted and used; otherwise, at least one of the elements was altered in transit, normally leading to wholesale rejection of the complete message.

For each AEAD algorithm, identified by a symbolic name (hereafter denoted as "`xxx`"), the following functions are defined:

- `br_xxx_init()`

  Initialise the AEAD algorithm, on a provided context structure. Exact parameters depend on the algorithm, and may include pointers to extra implementations and context structures. The secret key is provided at this point, either directly or indirectly.

- `br_xxx_reset()`

  Start a new AEAD computation. The nonce value is provided as parameter to this function.

- `br_xxx_aad_inject()`

  Inject some additional authenticated data. Additional data may be provided in several chunks of arbitrary length.

- `br_xxx_flip()`

  This function MUST be called after injecting all additional authenticated data, and before beginning to encrypt the plaintext (or decrypt the ciphertext).

- `br_xxx_run()`

  Process some plaintext (to encrypt) or ciphertext (to decrypt). Encryption/decryption is done in place. Data may be provided in several chunks of arbitrary length.

- `br_xxx_get_tag()`

  Compute the authentication tag. All message data (encrypted or decrypted) must have been injected at that point. Also, this call may modify internal context elements, so it may be called only once for a given AEAD computation.

- `br_xxx_check_tag()`

  An alternative to `br_xxx_get_tag()`, meant to be used by the receiver: the authentication tag is internally recomputed, and compared with the one provided as parameter.

This API makes the following assumptions on the AEAD algorithm:

- Encryption does not expand the size of the ciphertext; there is no padding. This is true of most modern AEAD modes such as GCM.
- The additional authenticated data must be processed first, before the encrypted/decrypted data.
- Nonce, plaintext and additional authenticated data all consist in an integral number of bytes. There is no provision to use elements whose length in bits is not a multiple of 8.

Each AEAD algorithm has its own requirements and limits on the sizes of additional data and plaintext. This API does not provide any way to report invalid usage; it is up to the caller to ensure that the provided key, nonce, and data elements all fit the algorithm's requirements.

## Object-Oriented API

Each context structure begins with a field (called `vtable`) that points to an instance of a structure that references the relevant functions through pointers. Each such structure contains the following:

- `reset`

  Pointer to the reset function, that allows starting a new computation.

- `aad_inject`

  Pointer to the additional authenticated data injection function.

- `flip`

  Pointer to the function that transitions from additional data to main message data processing.

- `get_tag`

  Pointer to the function that computes and returns the tag.

- `check_tag`

  Pointer to the function that computes and verifies the tag against a received value.

Note that there is no OOP method for context initialisation: the various AEAD algorithms have different requirements that would not map well to a single initialisation API.

The OOP API is not provided for CCM, due to its specific requirements (length of plaintext must be known in advance).

## Function Documentation

## ◆ br_ccm_aad_inject()

void br_ccm_aad_inject | ( | br_ccm_context * | ctx,
|  | const void * | data,
|  | size_t | len
| ) |  |

Inject additional authenticated data into CCM.

The provided data is injected into a running CCM computation. Additional data must be injected before the call to `br_ccm_flip()`. Additional data can be injected in several chunks of arbitrary length, but the total amount MUST exactly match the value which was provided to `br_ccm_reset()`.

Parameters

  ctx | CCM context structure.
  data | pointer to additional authenticated data.
  len | length of additional authenticated data (in bytes).

## ◆ br_ccm_check_tag()

uint32_t br_ccm_check_tag | ( | br_ccm_context * | ctx,
|  | const void * | tag
| ) |  |

Compute and check CCM authentication tag.

This function is an alternative to `br_ccm_get_tag()`, normally used on the receiving end (i.e. when decrypting value). The tag value is recomputed and compared with the provided tag value. If they match, 1 is returned; on mismatch, 0 is returned. A returned value of 0 means that the data or the tag was altered in transit, normally leading to wholesale rejection of the complete message.

Parameters

  ctx | CCM context structure.
  tag | tag value to compare with (up to 16 bytes).

Returns
  1 on success (exact match of tag value), 0 otherwise.

## ◆ br_ccm_flip()

void br_ccm_flip | ( | br_ccm_context * | ctx | ) |

Finish injection of additional authenticated data into CCM.

This function MUST be called before beginning the actual encryption or decryption (with `br_ccm_run()`), even if no additional authenticated data was injected. No additional authenticated data may be injected after this function call.

Parameters

  ctx | CCM context structure.

## ◆ br_ccm_get_tag()

size_t br_ccm_get_tag | ( | br_ccm_context * | ctx,
|  | void * | tag
| ) |  |

Compute CCM authentication tag.

Compute the CCM authentication tag. This call terminates the CCM run: all data must have been injected with `br_ccm_run()` (in zero, one or more successive calls). After this function has been called, no more data can br processed; a `br_ccm_reset()` call is required to start a new message.

The tag length was provided upon context initialisation (last call to `br_ccm_reset()`); it is returned by this function.

The tag value must normally be sent along with the encrypted data. When decrypting, the tag value must be recomputed and compared with the received tag: if the two tag values differ, then either the tag or the encrypted data was altered in transit. As an alternative to this function, the `br_ccm_check_tag()` function can be used to compute and check the tag value.

Parameters

  ctx | CCM context structure.
  tag | destination buffer for the tag (up to 16 bytes).

Returns
  the tag length (in bytes).

## ◆ br_ccm_init()

void br_ccm_init | ( | br_ccm_context * | ctx,
|  | const br_block_ctrcbc_class ** | bctx
| ) |  |

Initialize a CCM context.

A block cipher implementation, with its initialised context structure, is provided. The block cipher MUST use 16-byte blocks in CTR + CBC-MAC mode, and its secret key MUST have been already set in the provided context. The parameters are linked in the CCM context.

After this function has been called, the `br_ccm_reset()` function must be called, to provide the nonce for CCM computation.

Parameters

  ctx | CCM context structure.
  bctx | block cipher context (already initialised with secret key).

## ◆ br_ccm_reset()

int br_ccm_reset | ( | br_ccm_context * | ctx,
|  | const void * | nonce,
|  | size_t | nonce_len,
|  | uint64_t | aad_len,
|  | uint64_t | data_len,
|  | size_t | tag_len
| ) |  |

Reset a CCM context.

This function resets an already initialised CCM context for a new computation run. Implementations and keys are conserved. This function can be called at any time; it cancels any ongoing CCM computation that uses the provided context structure.

The `aad_len` parameter contains the total length, in bytes, of the additional authenticated data. It may be zero. That length MUST be exact.

The `data_len` parameter contains the total length, in bytes, of the data that will be injected (plaintext or ciphertext). That length MUST be exact. Moreover, that length MUST be less than 2^(8*(15-nonce_len)).

The nonce length (`nonce_len`), in bytes, must be in the 7..13 range (inclusive).

The tag length (`tag_len`), in bytes, must be in the 4..16 range, and be an even integer. Short tags mechanically allow for higher forgery probabilities; hence, tag sizes smaller than 12 bytes shall be used only with care.

It is critical to CCM security that nonce values are not repeated for the same encryption key. Random generation of nonces is not generally recommended, due to the relatively small maximum nonce value.

Returned value is 1 on success, 0 on error. An error is reported if the tag or nonce length is out of range, or if the plaintext/ciphertext length cannot be encoded with the specified nonce length.

Parameters

  ctx | CCM context structure.
  nonce | CCM nonce to use.
  nonce_len | CCM nonce length (in bytes, 7 to 13).
  aad_len | additional authenticated data length (in bytes).
  data_len | plaintext/ciphertext length (in bytes).
  tag_len | tag length (in bytes).

Returns
  1 on success, 0 on error.

## ◆ br_ccm_run()

void br_ccm_run | ( | br_ccm_context * | ctx,
|  | int | encrypt,
|  | void * | data,
|  | size_t | len
| ) |  |

Encrypt or decrypt some data with CCM.

Data encryption or decryption can be done after `br_ccm_flip()` has been called on the context. If `encrypt` is non-zero, then the provided data shall be plaintext, and it is encrypted in place. Otherwise, the data shall be ciphertext, and it is decrypted in place.

Data may be provided in several chunks of arbitrary length, provided that the total length exactly matches the length provided to the `br_ccm_reset()` call.

Parameters

  ctx | CCM context structure.
  encrypt | non-zero for encryption, zero for decryption.
  data | data to encrypt or decrypt.
  len | data length (in bytes).

## ◆ br_eax_aad_inject()

void br_eax_aad_inject | ( | br_eax_context * | ctx,
|  | const void * | data,
|  | size_t | len
| ) |  |

Inject additional authenticated data into EAX.

The provided data is injected into a running EAX computation. Additional data must be injected before the call to `br_eax_flip()`. Additional data can be injected in several chunks of arbitrary length; the total amount of additional authenticated data is unlimited.

Parameters

  ctx | EAX context structure.
  data | pointer to additional authenticated data.
  len | length of additional authenticated data (in bytes).

## ◆ br_eax_capture()

void br_eax_capture | ( | const br_eax_context * | ctx,
|  | br_eax_state * | st
| ) |  |

Capture pre-AAD state.

This function precomputes key-dependent data, and stores it in the provided `st` structure. This structure should then be used with `br_eax_reset_pre_aad()`, or updated with `br_eax_get_aad_mac()` and then used with `br_eax_reset_post_aad()`.

The EAX context structure is unmodified by this call.

Parameters

  ctx | EAX context structure.
  st | recipient for captured state.

## ◆ br_eax_check_tag()

uint32_t br_eax_check_tag | ( | br_eax_context * | ctx,
|  | const void * | tag
| ) |  |

Compute and check EAX authentication tag.

This function is an alternative to `br_eax_get_tag()`, normally used on the receiving end (i.e. when decrypting value). The tag value is recomputed and compared with the provided tag value. If they match, 1 is returned; on mismatch, 0 is returned. A returned value of 0 means that the data or the tag was altered in transit, normally leading to wholesale rejection of the complete message.

Parameters

  ctx | EAX context structure.
  tag | tag value to compare with (16 bytes).

Returns
  1 on success (exact match of tag value), 0 otherwise.

## ◆ br_eax_check_tag_trunc()

uint32_t br_eax_check_tag_trunc | ( | br_eax_context * | ctx,
|  | const void * | tag,
|  | size_t | len
| ) |  |

Compute and check EAX authentication tag (with truncation).

This function is an alternative to `br_eax_get_tag_trunc()`, normally used on the receiving end (i.e. when decrypting value). The tag value is recomputed and compared with the provided tag value. If they match, 1 is returned; on mismatch, 0 is returned. A returned value of 0 means that the data or the tag was altered in transit, normally leading to wholesale rejection of the complete message.

Tag length MUST be 16 bytes or less. The normal EAX tag length is 16 bytes. See `br_check_tag_trunc()` for some discussion on the potential perils of truncating authentication tags.

Parameters

  ctx | EAX context structure.
  tag | tag value to compare with.
  len | tag length (in bytes).

Returns
  1 on success (exact match of tag value), 0 otherwise.

## ◆ br_eax_flip()

void br_eax_flip | ( | br_eax_context * | ctx | ) |

Finish injection of additional authenticated data into EAX.

This function MUST be called before beginning the actual encryption or decryption (with `br_eax_run()`), even if no additional authenticated data was injected. No additional authenticated data may be injected after this function call.

Parameters

  ctx | EAX context structure.

## ◆ br_eax_get_aad_mac()

static void br_eax_get_aad_mac | ( | const br_eax_context * | ctx,
|  | br_eax_state * | st
| ) |  |
| inline static

Obtain a copy of the MAC on additional authenticated data.

This function may be called only after `br_eax_flip()`; it copies the AAD-specific MAC value into the provided state. The MAC value depends on the secret key and the additional data itself, but not on the nonce. The updated state `st` is meant to be used as parameter for a further `br_eax_reset_post_aad()` call.

Parameters

  ctx | EAX context structure.
  st | captured state to update.

## ◆ br_eax_get_tag()

void br_eax_get_tag | ( | br_eax_context * | ctx,
|  | void * | tag
| ) |  |

Compute EAX authentication tag.

Compute the EAX authentication tag. The tag is a 16-byte value which is written in the provided `tag` buffer. This call terminates the EAX run: no data may be processed with that EAX context afterwards, until `br_eax_reset()` is called to initiate a new EAX run.

The tag value must normally be sent along with the encrypted data. When decrypting, the tag value must be recomputed and compared with the received tag: if the two tag values differ, then either the tag or the encrypted data was altered in transit. As an alternative to this function, the `br_eax_check_tag()` function can be used to compute and check the tag value.

Parameters

  ctx | EAX context structure.
  tag | destination buffer for the tag (16 bytes).

## ◆ br_eax_get_tag_trunc()

void br_eax_get_tag_trunc | ( | br_eax_context * | ctx,
|  | void * | tag,
|  | size_t | len
| ) |  |

Compute EAX authentication tag (with truncation).

This function is similar to `br_eax_get_tag()`, except that it allows the tag to be truncated to a smaller length. The intended tag length is provided as `len` (in bytes); it MUST be no more than 16, but it may be smaller. Note that decreasing tag length mechanically makes forgeries easier; NIST SP 800-38D specifies that the tag length shall lie between 12 and 16 bytes (inclusive), but may be truncated down to 4 or 8 bytes, for specific applications that can tolerate it. It must also be noted that successful forgeries leak information on the authentication key, making subsequent forgeries easier. Therefore, tag truncation, and in particular truncation to sizes lower than 12 bytes, shall be envisioned only with great care.

The tag is written in the provided `tag` buffer. This call terminates the EAX run: no data may be processed with that EAX context afterwards, until `br_eax_reset()` is called to initiate a new EAX run.

The tag value must normally be sent along with the encrypted data. When decrypting, the tag value must be recomputed and compared with the received tag: if the two tag values differ, then either the tag or the encrypted data was altered in transit. As an alternative to this function, the `br_eax_check_tag_trunc()` function can be used to compute and check the tag value.

Parameters

  ctx | EAX context structure.
  tag | destination buffer for the tag.
  len | tag length (16 bytes or less).

## ◆ br_eax_init()

void br_eax_init | ( | br_eax_context * | ctx,
|  | const br_block_ctrcbc_class ** | bctx
| ) |  |

Initialize an EAX context.

A block cipher implementation, with its initialised context structure, is provided. The block cipher MUST use 16-byte blocks in CTR + CBC-MAC mode, and its secret key MUST have been already set in the provided context. The parameters are linked in the EAX context.

After this function has been called, the `br_eax_reset()` function must be called, to provide the nonce for EAX computation.

Parameters

  ctx | EAX context structure.
  bctx | block cipher context (already initialised with secret key).

## ◆ br_eax_reset()

void br_eax_reset | ( | br_eax_context * | ctx,
|  | const void * | nonce,
|  | size_t | len
| ) |  |

Reset an EAX context.

This function resets an already initialised EAX context for a new computation run. Implementations and keys are conserved. This function can be called at any time; it cancels any ongoing EAX computation that uses the provided context structure.

It is critical to EAX security that nonce values are not repeated for the same encryption key. Nonces can have arbitrary length. If nonces are randomly generated, then a nonce length of at least 128 bits (16 bytes) is recommended, to make nonce reuse probability sufficiently low.

Parameters

  ctx | EAX context structure.
  nonce | EAX nonce to use.
  len | EAX nonce length (in bytes).

## ◆ br_eax_reset_post_aad()

void br_eax_reset_post_aad | ( | br_eax_context * | ctx,
|  | const br_eax_state * | st,
|  | const void * | nonce,
|  | size_t | len
| ) |  |

Reset an EAX context with a post-AAD captured state.

This function is an alternative to `br_eax_reset()`, that reuses a previously captured state structure for lower per-message overhead. The state should have been populated with `br_eax_capture_state()` and then updated with `br_eax_get_aad_mac()`.

After this function is called, message data MUST be injected. The `br_eax_flip()` function MUST NOT be called. At least one byte of message data MUST be provided with `br_eax_run()`; empty messages are not supported with this reset mode.

Parameters

  ctx | EAX context structure.
  st | post-AAD captured state.
  nonce | EAX nonce to use.
  len | EAX nonce length (in bytes).

## ◆ br_eax_reset_pre_aad()

void br_eax_reset_pre_aad | ( | br_eax_context * | ctx,
|  | const br_eax_state * | st,
|  | const void * | nonce,
|  | size_t | len
| ) |  |

Reset an EAX context with a pre-AAD captured state.

This function is an alternative to `br_eax_reset()`, that reuses a previously captured state structure for lower per-message overhead. The state should have been populated with `br_eax_capture_state()` but not updated with `br_eax_get_aad_mac()`.

After this function is called, additional authenticated data MUST be injected. At least one byte of additional authenticated data MUST be provided with `br_eax_aad_inject()`; computation result will be incorrect if `br_eax_flip()` is called right away.

After injection of the AAD and call to `br_eax_flip()`, at least one message byte must be provided. Empty messages are not supported with this reset mode.

Parameters

  ctx | EAX context structure.
  st | pre-AAD captured state.
  nonce | EAX nonce to use.
  len | EAX nonce length (in bytes).

## ◆ br_eax_run()

void br_eax_run | ( | br_eax_context * | ctx,
|  | int | encrypt,
|  | void * | data,
|  | size_t | len
| ) |  |

Encrypt or decrypt some data with EAX.

Data encryption or decryption can be done after `br_eax_flip()` has been called on the context. If `encrypt` is non-zero, then the provided data shall be plaintext, and it is encrypted in place. Otherwise, the data shall be ciphertext, and it is decrypted in place.

Data may be provided in several chunks of arbitrary length.

Parameters

  ctx | EAX context structure.
  encrypt | non-zero for encryption, zero for decryption.
  data | data to encrypt or decrypt.
  len | data length (in bytes).

## ◆ br_gcm_aad_inject()

void br_gcm_aad_inject | ( | br_gcm_context * | ctx,
|  | const void * | data,
|  | size_t | len
| ) |  |

Inject additional authenticated data into GCM.

The provided data is injected into a running GCM computation. Additional data must be injected before the call to `br_gcm_flip()`. Additional data can be injected in several chunks of arbitrary length; the maximum total size of additional authenticated data is 2^64-1 bits.

Parameters

  ctx | GCM context structure.
  data | pointer to additional authenticated data.
  len | length of additional authenticated data (in bytes).

## ◆ br_gcm_check_tag()

uint32_t br_gcm_check_tag | ( | br_gcm_context * | ctx,
|  | const void * | tag
| ) |  |

Compute and check GCM authentication tag.

This function is an alternative to `br_gcm_get_tag()`, normally used on the receiving end (i.e. when decrypting value). The tag value is recomputed and compared with the provided tag value. If they match, 1 is returned; on mismatch, 0 is returned. A returned value of 0 means that the data or the tag was altered in transit, normally leading to wholesale rejection of the complete message.

Parameters

  ctx | GCM context structure.
  tag | tag value to compare with (16 bytes).

Returns
  1 on success (exact match of tag value), 0 otherwise.

## ◆ br_gcm_check_tag_trunc()

uint32_t br_gcm_check_tag_trunc | ( | br_gcm_context * | ctx,
|  | const void * | tag,
|  | size_t | len
| ) |  |

Compute and check GCM authentication tag (with truncation).

This function is an alternative to `br_gcm_get_tag_trunc()`, normally used on the receiving end (i.e. when decrypting value). The tag value is recomputed and compared with the provided tag value. If they match, 1 is returned; on mismatch, 0 is returned. A returned value of 0 means that the data or the tag was altered in transit, normally leading to wholesale rejection of the complete message.

Tag length MUST be 16 bytes or less. The normal GCM tag length is 16 bytes. See `br_check_tag_trunc()` for some discussion on the potential perils of truncating authentication tags.

Parameters

  ctx | GCM context structure.
  tag | tag value to compare with.
  len | tag length (in bytes).

Returns
  1 on success (exact match of tag value), 0 otherwise.

## ◆ br_gcm_flip()

void br_gcm_flip | ( | br_gcm_context * | ctx | ) |

Finish injection of additional authenticated data into GCM.

This function MUST be called before beginning the actual encryption or decryption (with `br_gcm_run()`), even if no additional authenticated data was injected. No additional authenticated data may be injected after this function call.

Parameters

  ctx | GCM context structure.

## ◆ br_gcm_get_tag()

void br_gcm_get_tag | ( | br_gcm_context * | ctx,
|  | void * | tag
| ) |  |

Compute GCM authentication tag.

Compute the GCM authentication tag. The tag is a 16-byte value which is written in the provided `tag` buffer. This call terminates the GCM run: no data may be processed with that GCM context afterwards, until `br_gcm_reset()` is called to initiate a new GCM run.

The tag value must normally be sent along with the encrypted data. When decrypting, the tag value must be recomputed and compared with the received tag: if the two tag values differ, then either the tag or the encrypted data was altered in transit. As an alternative to this function, the `br_gcm_check_tag()` function can be used to compute and check the tag value.

Parameters

  ctx | GCM context structure.
  tag | destination buffer for the tag (16 bytes).

## ◆ br_gcm_get_tag_trunc()

void br_gcm_get_tag_trunc | ( | br_gcm_context * | ctx,
|  | void * | tag,
|  | size_t | len
| ) |  |

Compute GCM authentication tag (with truncation).

This function is similar to `br_gcm_get_tag()`, except that it allows the tag to be truncated to a smaller length. The intended tag length is provided as `len` (in bytes); it MUST be no more than 16, but it may be smaller. Note that decreasing tag length mechanically makes forgeries easier; NIST SP 800-38D specifies that the tag length shall lie between 12 and 16 bytes (inclusive), but may be truncated down to 4 or 8 bytes, for specific applications that can tolerate it. It must also be noted that successful forgeries leak information on the authentication key, making subsequent forgeries easier. Therefore, tag truncation, and in particular truncation to sizes lower than 12 bytes, shall be envisioned only with great care.

The tag is written in the provided `tag` buffer. This call terminates the GCM run: no data may be processed with that GCM context afterwards, until `br_gcm_reset()` is called to initiate a new GCM run.

The tag value must normally be sent along with the encrypted data. When decrypting, the tag value must be recomputed and compared with the received tag: if the two tag values differ, then either the tag or the encrypted data was altered in transit. As an alternative to this function, the `br_gcm_check_tag_trunc()` function can be used to compute and check the tag value.

Parameters

  ctx | GCM context structure.
  tag | destination buffer for the tag.
  len | tag length (16 bytes or less).

## ◆ br_gcm_init()

void br_gcm_init | ( | br_gcm_context * | ctx,
|  | const br_block_ctr_class ** | bctx,
|  | br_ghash | gh
| ) |  |

Initialize a GCM context.

A block cipher implementation, with its initialised context structure, is provided. The block cipher MUST use 16-byte blocks in CTR mode, and its secret key MUST have been already set in the provided context. A GHASH implementation must also be provided. The parameters are linked in the GCM context.

After this function has been called, the `br_gcm_reset()` function must be called, to provide the IV for GCM computation.

Parameters

  ctx | GCM context structure.
  bctx | block cipher context (already initialised with secret key).
  gh | GHASH implementation.

## ◆ br_gcm_reset()

void br_gcm_reset | ( | br_gcm_context * | ctx,
|  | const void * | iv,
|  | size_t | len
| ) |  |

Reset a GCM context.

This function resets an already initialised GCM context for a new computation run. Implementations and keys are conserved. This function can be called at any time; it cancels any ongoing GCM computation that uses the provided context structure.

The provided IV is a nonce. It is critical to GCM security that IV values are not repeated for the same encryption key. IV can have arbitrary length (up to 2^64-1 bits), but the "normal" length is 96 bits (12 bytes).

Parameters

  ctx | GCM context structure.
  iv | GCM nonce to use.
  len | GCM nonce length (in bytes).

## ◆ br_gcm_run()

void br_gcm_run | ( | br_gcm_context * | ctx,
|  | int | encrypt,
|  | void * | data,
|  | size_t | len
| ) |  |

Encrypt or decrypt some data with GCM.

Data encryption or decryption can be done after `br_gcm_flip()` has been called on the context. If `encrypt` is non-zero, then the provided data shall be plaintext, and it is encrypted in place. Otherwise, the data shall be ciphertext, and it is decrypted in place.

Data may be provided in several chunks of arbitrary length. The maximum total length for data is 2^39-256 bits, i.e. about 65 gigabytes.

Parameters

  ctx | GCM context structure.
  encrypt | non-zero for encryption, zero for decryption.
  data | data to encrypt or decrypt.
  len | data length (in bytes).

## Variable Documentation

## ◆ br_eax_vtable

const br_aead_class br_eax_vtable
| extern

Class instance for EAX.

## ◆ br_gcm_vtable

const br_aead_class br_gcm_vtable
| extern

Class instance for GCM.