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  )

inlinestatic

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

Class instance for EAX.

br_gcm_vtable

const br_aead_class br_gcm_vtable

Class instance for GCM.