This file contains GCM definitions and functions. More...

#include "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include "mbedtls/cipher.h"
#include <stdint.h>
#include "gcm_alt.h"

Include dependency graph for gcm.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	MBEDTLS_GCM_ENCRYPT 1

#define	MBEDTLS_GCM_DECRYPT 0

#define	MBEDTLS_ERR_GCM_AUTH_FAILED -0x0012

#define	MBEDTLS_ERR_GCM_BAD_INPUT -0x0014

#define	MBEDTLS_ERR_GCM_BUFFER_TOO_SMALL -0x0016

Functions
void	mbedtls_gcm_init (mbedtls_gcm_context *ctx)
	This function initializes the specified GCM context, to make references valid, and prepares the context for mbedtls_gcm_setkey() or mbedtls_gcm_free(). More...

int	mbedtls_gcm_setkey (mbedtls_gcm_context ctx, mbedtls_cipher_id_t cipher, const unsigned char key, unsigned int keybits)
	This function associates a GCM context with a cipher algorithm and a key. More...

int	mbedtls_gcm_crypt_and_tag (mbedtls_gcm_context ctx, int mode, size_t length, const unsigned char iv, size_t iv_len, const unsigned char add, size_t add_len, const unsigned char input, unsigned char output, size_t tag_len, unsigned char tag)
	This function performs GCM encryption or decryption of a buffer. More...

int	mbedtls_gcm_auth_decrypt (mbedtls_gcm_context ctx, size_t length, const unsigned char iv, size_t iv_len, const unsigned char add, size_t add_len, const unsigned char tag, size_t tag_len, const unsigned char input, unsigned char output)
	This function performs a GCM authenticated decryption of a buffer. More...

int	mbedtls_gcm_starts (mbedtls_gcm_context ctx, int mode, const unsigned char iv, size_t iv_len)
	This function starts a GCM encryption or decryption operation. More...

int	mbedtls_gcm_update_ad (mbedtls_gcm_context ctx, const unsigned char add, size_t add_len)
	This function feeds an input buffer as associated data (authenticated but not encrypted data) in a GCM encryption or decryption operation. More...

int	mbedtls_gcm_update (mbedtls_gcm_context ctx, const unsigned char input, size_t input_length, unsigned char output, size_t output_size, size_t output_length)
	This function feeds an input buffer into an ongoing GCM encryption or decryption operation. More...

int	mbedtls_gcm_finish (mbedtls_gcm_context ctx, unsigned char output, size_t output_size, size_t output_length, unsigned char tag, size_t tag_len)
	This function finishes the GCM operation and generates the authentication tag. More...

void	mbedtls_gcm_free (mbedtls_gcm_context *ctx)
	This function clears a GCM context and the underlying cipher sub-context. More...

int	mbedtls_gcm_self_test (int verbose)
	The GCM checkup routine. More...

Detailed Description

This file contains GCM definitions and functions.

The Galois/Counter Mode (GCM) for 128-bit block ciphers is defined in D. McGrew, J. Viega, The Galois/Counter Mode of Operation (GCM), Natl. Inst. Stand. Technol.

For more information on GCM, see NIST SP 800-38D: Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC.

Definition in file gcm.h.

Macro Definition Documentation

#define MBEDTLS_ERR_GCM_AUTH_FAILED -0x0012

Authenticated decryption failed.

Definition at line 45 of file gcm.h.

#define MBEDTLS_ERR_GCM_BAD_INPUT -0x0014

Bad input parameters to function.

Definition at line 47 of file gcm.h.

#define MBEDTLS_ERR_GCM_BUFFER_TOO_SMALL -0x0016

An output buffer is too small.

Definition at line 49 of file gcm.h.

#define MBEDTLS_GCM_DECRYPT 0

Definition at line 42 of file gcm.h.

#define MBEDTLS_GCM_ENCRYPT 1

Definition at line 41 of file gcm.h.

Function Documentation

int mbedtls_gcm_auth_decrypt	(	mbedtls_gcm_context *	ctx,
		size_t	length,
		const unsigned char *	iv,
		size_t	iv_len,
		const unsigned char *	add,
		size_t	add_len,
		const unsigned char *	tag,
		size_t	tag_len,
		const unsigned char *	input,
		unsigned char *	output
	)

This function performs a GCM authenticated decryption of a buffer.

Note: For decryption, the output buffer cannot be the same as input buffer. If the buffers overlap, the output buffer must trail at least 8 Bytes behind the input buffer.

Parameters

ctx	The GCM context. This must be initialized.
length	The length of the ciphertext to decrypt, which is also the length of the decrypted plaintext.
iv	The initialization vector. This must be a readable buffer of at least `iv_len` Bytes.
iv_len	The length of the IV.
add	The buffer holding the additional data. This must be of at least that size in Bytes.
add_len	The length of the additional data.
tag	The buffer holding the tag to verify. This must be a readable buffer of at least `tag_len` Bytes.
tag_len	The length of the tag to verify.
input	The buffer holding the ciphertext. If `length` is greater than zero, this must be a readable buffer of at least that size.
output	The buffer for holding the decrypted plaintext. If `length` is greater than zero, this must be a writable buffer of at least that size.

Returns: 0 if successful and authenticated.; MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match.; MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are not valid or a cipher-specific error code if the decryption failed.

int mbedtls_gcm_crypt_and_tag	(	mbedtls_gcm_context *	ctx,
		int	mode,
		size_t	length,
		const unsigned char *	iv,
		size_t	iv_len,
		const unsigned char *	add,
		size_t	add_len,
		const unsigned char *	input,
		unsigned char *	output,
		size_t	tag_len,
		unsigned char *	tag
	)

This function performs GCM encryption or decryption of a buffer.

Note: For encryption, the output buffer can be the same as the input buffer. For decryption, the output buffer cannot be the same as input buffer. If the buffers overlap, the output buffer must trail at least 8 Bytes behind the input buffer.

Warning: When this function performs a decryption, it outputs the authentication tag and does not verify that the data is authentic. You should use this function to perform encryption only. For decryption, use mbedtls_gcm_auth_decrypt() instead.

Parameters

ctx	The GCM context to use for encryption or decryption. This must be initialized.
mode	The operation to perform: MBEDTLS_GCM_ENCRYPT to perform authenticated encryption. The ciphertext is written to `output` and the authentication tag is written to `tag`. MBEDTLS_GCM_DECRYPT to perform decryption. The plaintext is written to `output` and the authentication tag is written to `tag`. Note that this mode is not recommended, because it does not verify the authenticity of the data. For this reason, you should use mbedtls_gcm_auth_decrypt() instead of calling this function in decryption mode.
length	The length of the input data, which is equal to the length of the output data.
iv	The initialization vector. This must be a readable buffer of at least `iv_len` Bytes.
iv_len	The length of the IV.
add	The buffer holding the additional data. This must be of at least that size in Bytes.
add_len	The length of the additional data.
input	The buffer holding the input data. If `length` is greater than zero, this must be a readable buffer of at least that size in Bytes.
output	The buffer for holding the output data. If `length` is greater than zero, this must be a writable buffer of at least that size in Bytes.
tag_len	The length of the tag to generate.
tag	The buffer for holding the tag. This must be a writable buffer of at least `tag_len` Bytes.

Returns: 0 if the encryption or decryption was performed successfully. Note that in MBEDTLS_GCM_DECRYPT mode, this does not indicate that the data is authentic.; MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are not valid or a cipher-specific error code if the encryption or decryption failed.

int mbedtls_gcm_finish	(	mbedtls_gcm_context *	ctx,
		unsigned char *	output,
		size_t	output_size,
		size_t *	output_length,
		unsigned char *	tag,
		size_t	tag_len
	)

This function finishes the GCM operation and generates the authentication tag.

It wraps up the GCM stream, and generates the tag. The tag can have a maximum length of 16 Bytes.

Parameters

ctx	The GCM context. This must be initialized.
tag	The buffer for holding the tag. This must be a writable buffer of at least `tag_len` Bytes.
tag_len	The length of the tag to generate. This must be at least four.
output	The buffer for the final output. If `output_size` is nonzero, this must be a writable buffer of at least `output_size` bytes.
output_size	The size of the `output` buffer in bytes. This must be large enough for the output that mbedtls_gcm_update() has not produced. In particular: If mbedtls_gcm_update() produces immediate output, or if the total input size is a multiple of `16`, then mbedtls_gcm_finish() never produces any output, so `output_size` can be `0`. `output_size` never needs to be more than `15`.
output_length	On success, `output_length` contains the actual length of the output written in `output`. On failure, the content of `output_length` is unspecified.

Returns: 0 on success.; MBEDTLS_ERR_GCM_BAD_INPUT on failure: invalid value of tag_len, or output_size too small.

void mbedtls_gcm_free ( mbedtls_gcm_context * ctx )

This function clears a GCM context and the underlying cipher sub-context.

Parameters

ctx	The GCM context to clear. If this is `NULL`, the call has no effect. Otherwise, this must be initialized.

void mbedtls_gcm_init ( mbedtls_gcm_context * ctx )

This function initializes the specified GCM context, to make references valid, and prepares the context for mbedtls_gcm_setkey() or mbedtls_gcm_free().

The function does not bind the GCM context to a particular cipher, nor set the key. For this purpose, use mbedtls_gcm_setkey().

Parameters

ctx	The GCM context to initialize. This must not be `NULL`.

int mbedtls_gcm_self_test ( int verbose )

The GCM checkup routine.

Returns: 0 on success.; 1 on failure.

int mbedtls_gcm_setkey	(	mbedtls_gcm_context *	ctx,
		mbedtls_cipher_id_t	cipher,
		const unsigned char *	key,
		unsigned int	keybits
	)

This function associates a GCM context with a cipher algorithm and a key.

Parameters

ctx	The GCM context. This must be initialized.
cipher	The 128-bit block cipher to use.
key	The encryption key. This must be a readable buffer of at least `keybits` bits.
keybits	The key size in bits. Valid options are: 128 bits 192 bits 256 bits

Returns: 0 on success.; A cipher-specific error code on failure.

int mbedtls_gcm_starts	(	mbedtls_gcm_context *	ctx,
		int	mode,
		const unsigned char *	iv,
		size_t	iv_len
	)

This function starts a GCM encryption or decryption operation.

Parameters

ctx	The GCM context. This must be initialized.
mode	The operation to perform: MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT.
iv	The initialization vector. This must be a readable buffer of at least `iv_len` Bytes.
iv_len	The length of the IV.

Returns: 0 on success.

int mbedtls_gcm_update	(	mbedtls_gcm_context *	ctx,
		const unsigned char *	input,
		size_t	input_length,
		unsigned char *	output,
		size_t	output_size,
		size_t *	output_length
	)

This function feeds an input buffer into an ongoing GCM encryption or decryption operation.

You may call this function zero, one or more times to pass successive parts of the input: the plaintext to encrypt, or the ciphertext (not including the tag) to decrypt. After the last part of the input, call mbedtls_gcm_finish().

This function may produce output in one of the following ways:

Immediate output: the output length is always equal to the input length.
Buffered output: the output consists of a whole number of 16-byte blocks. If the total input length so far (not including associated data) is 16 * B + A with A < 16 then the total output length is 16 * B.

In particular:

It is always correct to call this function with output_size >= input_length + 15.
If input_length is a multiple of 16 for all the calls to this function during an operation, then it is correct to use output_size = input_length.

Note: For decryption, the output buffer cannot be the same as input buffer. If the buffers overlap, the output buffer must trail at least 8 Bytes behind the input buffer.

Parameters

ctx	The GCM context. This must be initialized.
input	The buffer holding the input data. If `input_length` is greater than zero, this must be a readable buffer of at least `input_length` bytes.
input_length	The length of the input data in bytes.
output	The buffer for the output data. If `output_size` is greater than zero, this must be a writable buffer of of at least `output_size` bytes.
output_size	The size of the output buffer in bytes. See the function description regarding the output size.
output_length	On success, `output_length` contains the actual length of the output written in `output`. On failure, the content of `output_length` is unspecified.

Returns: 0 on success.; MBEDTLS_ERR_GCM_BAD_INPUT on failure: total input length too long, unsupported input/output buffer overlap detected, or output_size too small.

int mbedtls_gcm_update_ad	(	mbedtls_gcm_context *	ctx,
		const unsigned char *	add,
		size_t	add_len
	)

This function feeds an input buffer as associated data (authenticated but not encrypted data) in a GCM encryption or decryption operation.

Call this function after mbedtls_gcm_starts() to pass the associated data. If the associated data is empty, you do not need to call this function. You may not call this function after calling mbedtls_cipher_update().

Parameters

ctx	The GCM context. This must have been started with mbedtls_gcm_starts() and must not have yet received any input with mbedtls_gcm_update().
add	The buffer holding the additional data, or `NULL` if `add_len` is `0`.
add_len	The length of the additional data. If `0`, `add` may be `NULL`.

Returns: 0 on success.

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation