BearSSL: br_aead_class Struct Reference

BearSSL

Loading...
Searching...
No Matches
Data Fields
br_aead_class Struct Reference

Class type of an AEAD algorithm. More...

`#include <bearssl_aead.h>`

## Data Fields
size_t | tag_size
| Size (in bytes) of authentication tags created by this AEAD algorithm.
void(* | reset )(const br_aead_class **cc, const void *iv, size_t len)
| Reset an AEAD context.
void(* | aad_inject )(const br_aead_class **cc, const void *data, size_t len)
| Inject additional authenticated data.
void(* | flip )(const br_aead_class **cc)
| Finish injection of additional authenticated data.
void(* | run )(const br_aead_class **cc, int encrypt, void *data, size_t len)
| Encrypt or decrypt some data.
void(* | get_tag )(const br_aead_class **cc, void *tag)
| Compute authentication tag.
uint32_t(* | check_tag )(const br_aead_class **cc, const void *tag)
| Compute and check authentication tag.
void(* | get_tag_trunc )(const br_aead_class **cc, void *tag, size_t len)
| Compute authentication tag (with truncation).
uint32_t(* | check_tag_trunc )(const br_aead_class **cc, const void *tag, size_t len)
| Compute and check authentication tag (with truncation).

## Detailed Description

Class type of an AEAD algorithm.

## Field Documentation

## ◆ aad_inject

void(* br_aead_class::aad_inject) (const br_aead_class **cc, const void *data, size_t len)

Inject additional authenticated data.

The provided data is injected into a running AEAD computation. Additional data must be injected before the call to flip(). Additional data can be injected in several chunks of arbitrary length.

Parameters

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

## ◆ check_tag

uint32_t(* br_aead_class::check_tag) (const br_aead_class **cc, const void *tag)

Compute and check authentication tag.

This function is an alternative to get_tag(), and is normally used on the receiving end (i.e. when decrypting messages). 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 depends on the AEAD algorithm.

Parameters

  cc | AEAD context structure.
  tag | tag value to compare with.

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

## ◆ check_tag_trunc

uint32_t(* br_aead_class::check_tag_trunc) (const br_aead_class **cc, const void *tag, size_t len)

Compute and check authentication tag (with truncation).

This function is similar to check_tag() except that it works over an explicit tag length. See get_tag() for a discussion of explicit tag lengths; the range of allowed tag lengths depends on the algorithm.

Parameters

  cc | AEAD context structure.
  tag | tag value to compare with.
  len | tag length (in bytes).

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

## ◆ flip

void(* br_aead_class::flip) (const br_aead_class **cc)

Finish injection of additional authenticated data.

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

Parameters

  cc | AEAD context structure.

## ◆ get_tag

void(* br_aead_class::get_tag) (const br_aead_class **cc, void *tag)

Compute authentication tag.

Compute the AEAD authentication tag. The tag length depends on the AEAD algorithm; it is written in the provided tag buffer. This call terminates the AEAD run: no data may be processed with that AEAD context afterwards, until reset() is called to initiate a new AEAD 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 check_tag() function may be used to compute and check the tag value.

Tag length depends on the AEAD algorithm.

Parameters

  cc | AEAD context structure.
  tag | destination buffer for the tag.

## ◆ get_tag_trunc

void(* br_aead_class::get_tag_trunc) (const br_aead_class **cc, void *tag, size_t len)

Compute authentication tag (with truncation).

This function is similar to get_tag(), except that the tag length is provided. Some AEAD algorithms allow several tag lengths, usually by truncating the normal tag. Shorter tags mechanically increase success probability of forgeries. The range of allowed tag lengths depends on the algorithm.

Parameters

  cc | AEAD context structure.
  tag | destination buffer for the tag.
  len | tag length (in bytes).

## ◆ reset

void(* br_aead_class::reset) (const br_aead_class **cc, const void *iv, size_t len)

Reset an AEAD context.

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

The provided IV is a nonce. Each AEAD algorithm has its own requirements on IV size and contents; for most of them, it is crucial to security that each nonce value is used only once for a given secret key.

Parameters

  cc | AEAD context structure.
  iv | AEAD nonce to use.
  len | AEAD nonce length (in bytes).

## ◆ run

void(* br_aead_class::run) (const br_aead_class **cc, int encrypt, void *data, size_t len)

Encrypt or decrypt some data.

Data encryption or decryption can be done after 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

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

## ◆ tag_size

size_t br_aead_class::tag_size

Size (in bytes) of authentication tags created by this AEAD algorithm.

The documentation for this struct was generated from the following file:

- bearssl_aead.h