Kenji Arai / mbed-os_TYBLE16

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

Embed: (wiki syntax)

« Back to documentation index

gcm.h File Reference
Data Structures | Typedefs | Functions

gcm.h File Reference

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

Go to the source code of this file.

Data Structures

struct  mbedtls_gcm_context
 The GCM context structure. More...

Typedefs

typedef struct mbedtls_gcm_context mbedtls_gcm_context
 The GCM context structure.

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().
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.
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.
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.
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.
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.
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.
void mbedtls_gcm_free (mbedtls_gcm_context *ctx)
 This function clears a GCM context and the underlying cipher sub-context.
int mbedtls_gcm_self_test (int verbose)
 The GCM checkup routine.

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.

Typedef Documentation

typedef struct mbedtls_gcm_context mbedtls_gcm_context

The GCM context structure.

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. This must be initialized.
lengthThe length of the ciphertext to decrypt, which is also the length of the decrypted plaintext.
ivThe initialization vector. This must be a readable buffer of at least iv_len Bytes.
iv_lenThe length of the IV.
addThe buffer holding the additional data. This must be of at least that size in Bytes.
add_lenThe length of the additional data.
tagThe buffer holding the tag to verify. This must be a readable buffer of at least tag_len Bytes.
tag_lenThe length of the tag to verify.
inputThe buffer holding the ciphertext. If length is greater than zero, this must be a readable buffer of at least that size.
outputThe 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.

Definition at line 500 of file gcm.c.

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:
ctxThe GCM context to use for encryption or decryption. This must be initialized.
modeThe 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.
lengthThe length of the input data, which is equal to the length of the output data.
ivThe initialization vector. This must be a readable buffer of at least iv_len Bytes.
iv_lenThe length of the IV.
addThe buffer holding the additional data. This must be of at least that size in Bytes.
add_lenThe length of the additional data.
inputThe buffer holding the input data. If length is greater than zero, this must be a readable buffer of at least that size in Bytes.
outputThe 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_lenThe length of the tag to generate.
tagThe buffer for holding the tag. This must be a readable 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.

Definition at line 467 of file gcm.c.

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. This must be initialized.
tagThe buffer for holding the tag. This must be a readable buffer of at least tag_len Bytes.
tag_lenThe length of the tag to generate. This must be at least four.
Returns:
0 on success.
MBEDTLS_ERR_GCM_BAD_INPUT on failure.

Definition at line 426 of file gcm.c.

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. If this is NULL, the call has no effect. Otherwise, this must be initialized.

Definition at line 543 of file gcm.c.

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. This must not be NULL.

Definition at line 92 of file gcm.c.

int mbedtls_gcm_self_test ( int  verbose )

The GCM checkup routine.

Returns:
0 on success.
1 on failure.

Definition at line 781 of file gcm.c.

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. This must be initialized.
cipherThe 128-bit block cipher to use.
keyThe encryption key. This must be a readable buffer of at least keybits bits.
keybitsThe key size in bits. Valid options are:

  • 128 bits
  • 192 bits
  • 256 bits
Returns:
0 on success.
A cipher-specific error code on failure.

Definition at line 166 of file gcm.c.

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. This must be initialized.
modeThe operation to perform: MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT.
ivThe initialization vector. This must be a readable buffer of at least iv_len Bytes.
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 may be NULL.
Returns:
0 on success.

Definition at line 276 of file gcm.c.

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. This must be initialized.
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. If length is greater than zero, this must be a readable buffer of at least that size in Bytes.
outputThe 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.
Returns:
0 on success.
MBEDTLS_ERR_GCM_BAD_INPUT on failure.

Definition at line 363 of file gcm.c.

Generated on Tue Jul 12 2022 13:55:11 by  doxygen 1.7.2