mbed TLS  Version 2.8.0
SSL/TLS Library for the Embedded Space
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
gcm.h File Reference

Data Structures

struct  mbedtls_gcm_context
 The GCM context structure. More...
 

Macros

#define MBEDTLS_GCM_ENCRYPT   1
 
#define MBEDTLS_GCM_DECRYPT   0
 
#define MBEDTLS_ERR_GCM_AUTH_FAILED   -0x0012
 Authenticated decryption failed. More...
 
#define MBEDTLS_ERR_GCM_HW_ACCEL_FAILED   -0x0013
 GCM hardware accelerator failed. More...
 
#define MBEDTLS_ERR_GCM_BAD_INPUT   -0x0014
 Bad input parameters to function. More...
 

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, const unsigned char *add, size_t add_len)
 This function starts a GCM encryption or decryption operation. More...
 
int mbedtls_gcm_update (mbedtls_gcm_context *ctx, size_t length, const unsigned char *input, unsigned char *output)
 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 *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...
 

Description

Galois/Counter Mode (GCM) for 128-bit block ciphers, as 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.


Data Structure Documentation

struct mbedtls_gcm_context

The GCM context structure.

Data Fields
uint64_t add_len

The total length of the additional data.

unsigned char base_ectr[16]

The first ECTR for tag.

unsigned char buf[16]

The buf working value.

mbedtls_cipher_context_t cipher_ctx

The cipher context used.

uint64_t HH[16]

Precalculated HTable high.

uint64_t HL[16]

Precalculated HTable low.

uint64_t len

The total length of the encrypted data.

int mode

The operation to perform: #MBEDTLS_GCM_ENCRYPT or #MBEDTLS_GCM_DECRYPT.

unsigned char y[16]

The Y working value.

Macro Definition Documentation

#define MBEDTLS_ERR_GCM_AUTH_FAILED   -0x0012

Authenticated decryption failed.

#define MBEDTLS_ERR_GCM_BAD_INPUT   -0x0014

Bad input parameters to function.

#define MBEDTLS_ERR_GCM_HW_ACCEL_FAILED   -0x0013

GCM hardware accelerator failed.

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
ctxThe GCM context.
lengthThe length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
ivThe initialization vector.
iv_lenThe length of the IV.
addThe buffer holding the additional data.
add_lenThe length of the additional data.
tagThe buffer holding the tag.
tag_lenThe length of the tag.
inputThe buffer holding the input data.
outputThe buffer for holding the output data.
Returns
0 if successful and authenticated, or MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match.
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.
Parameters
ctxThe GCM context to use for encryption or decryption.
modeThe operation to perform: #MBEDTLS_GCM_ENCRYPT or #MBEDTLS_GCM_DECRYPT.
lengthThe length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
ivThe initialization vector.
iv_lenThe length of the IV.
addThe buffer holding the additional data.
add_lenThe length of the additional data.
inputThe buffer holding the input data.
outputThe buffer for holding the output data.
tag_lenThe length of the tag to generate.
tagThe buffer for holding the tag.
Returns
0 on success.
int mbedtls_gcm_finish ( mbedtls_gcm_context ctx,
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
ctxThe GCM context.
tagThe buffer for holding the tag.
tag_lenThe length of the tag to generate. Must be at least four.
Returns
0 on success, or MBEDTLS_ERR_GCM_BAD_INPUT on failure.
void mbedtls_gcm_free ( mbedtls_gcm_context ctx)

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

Parameters
ctxThe GCM context to clear.
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
ctxThe GCM context to initialize.
int mbedtls_gcm_self_test ( int  verbose)

The GCM checkup routine.

Returns
0 on success, or 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
ctxThe GCM context to initialize.
cipherThe 128-bit block cipher to use.
keyThe encryption key.
keybitsThe key size in bits. Valid options are:
  • 128 bits
  • 192 bits
  • 256 bits
Returns
0 on success, or a cipher specific error code.
int mbedtls_gcm_starts ( mbedtls_gcm_context ctx,
int  mode,
const unsigned char *  iv,
size_t  iv_len,
const unsigned char *  add,
size_t  add_len 
)

This function starts a GCM encryption or decryption operation.

Parameters
ctxThe GCM context.
modeThe operation to perform: #MBEDTLS_GCM_ENCRYPT or #MBEDTLS_GCM_DECRYPT.
ivThe initialization vector.
iv_lenThe length of the IV.
addThe buffer holding the additional data, or NULL if add_len is 0.
add_lenThe length of the additional data. If 0, add is NULL.
Returns
0 on success.
int mbedtls_gcm_update ( mbedtls_gcm_context ctx,
size_t  length,
const unsigned char *  input,
unsigned char *  output 
)

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

` The function expects input to be a multiple of 16 Bytes. Only the last call before calling mbedtls_gcm_finish() can be less than 16 Bytes.

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
ctxThe GCM context.
lengthThe length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
inputThe buffer holding the input data.
outputThe buffer for holding the output data.
Returns
0 on success, or MBEDTLS_ERR_GCM_BAD_INPUT on failure.