gcm.h
mbedtls/config.h
mbedtls/cipher.h
stdint.h
crypto_struct.h
mbedtls/check_config.h
mbedtls/cipher.h
mbedtls/config.h
gcm.h
mbedtls/platform_time.h
mbedtls/platform_util.h
limits.h
stddef.h
stdint.h
time.h
gcm.h
crypto.h
crypto_struct.h
mbedtls_gcm_context
MBEDTLS_GCM_ENCRYPT
1
MBEDTLS_GCM_DECRYPT
0
MBEDTLS_ERR_GCM_AUTH_FAILED
-0x0012

Authenticated decryption failed.

MBEDTLS_ERR_GCM_HW_ACCEL_FAILED
-0x0013

GCM hardware accelerator failed.

MBEDTLS_ERR_GCM_BAD_INPUT
-0x0014

Bad input parameters to function.

struct mbedtls_gcm_context typedef struct mbedtls_gcm_context mbedtls_gcm_context mbedtls_gcm_context

The GCM context structure.

void void mbedtls_gcm_init (mbedtls_gcm_context *ctx) 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().

ctx

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

int int mbedtls_gcm_setkey (mbedtls_gcm_context *ctx, mbedtls_cipher_id_t cipher, const unsigned char *key, unsigned int keybits) 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.

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

`0` on success.

A cipher-specific error code on failure.

int 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) 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.

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.

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.

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.

`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 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) 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.

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.

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.

`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 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) 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.

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.

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`.

`0` on success.

int int mbedtls_gcm_update (mbedtls_gcm_context *ctx, size_t length, const unsigned char *input, unsigned char *output) 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.

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.

ctx

The GCM context. This must be initialized.

length

The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().

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.

`0` on success.

MBEDTLS_ERR_GCM_BAD_INPUT on failure.

int int mbedtls_gcm_finish (mbedtls_gcm_context *ctx, unsigned char *tag, size_t tag_len) 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.

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.

`0` on success.

MBEDTLS_ERR_GCM_BAD_INPUT on failure.

void void mbedtls_gcm_free (mbedtls_gcm_context *ctx) mbedtls_gcm_free mbedtls_gcm_context * ctx

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

ctx

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

int int mbedtls_gcm_self_test (int verbose) mbedtls_gcm_self_test int verbose

The GCM checkup routine.

`0` on success.

`1` on failure.

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.

    /*
    *CopyrightTheMbedTLSContributors
    *SPDX-License-Identifier:Apache-2.0ORGPL-2.0-or-later
    */

    #ifndefMBEDTLS_GCM_H
    #defineMBEDTLS_GCM_H

    #if!defined(MBEDTLS_CONFIG_FILE)
    #include"mbedtls/config.h"
    #else
    #includeMBEDTLS_CONFIG_FILE
    #endif

    #include"mbedtls/cipher.h"

    #include<stdint.h>

    #defineMBEDTLS_GCM_ENCRYPT1
    #defineMBEDTLS_GCM_DECRYPT0

    #defineMBEDTLS_ERR_GCM_AUTH_FAILED-0x0012

    /*MBEDTLS_ERR_GCM_HW_ACCEL_FAILEDisdeprecatedandshouldnotbeused.*/
    #defineMBEDTLS_ERR_GCM_HW_ACCEL_FAILED-0x0013

    #defineMBEDTLS_ERR_GCM_BAD_INPUT-0x0014

    #ifdef__cplusplus
    extern"C"{
    #endif

    #if!defined(MBEDTLS_GCM_ALT)

    typedefstructmbedtls_gcm_context{
    mbedtls_cipher_context_tcipher_ctx;
    uint64_tHL[16];
    uint64_tHH[16];
    uint64_tlen;
    uint64_tadd_len;
    unsignedcharbase_ectr[16];
    unsignedchary[16];
    unsignedcharbuf[16];
    intmode;
    }
    mbedtls_gcm_context;

    #else/*!MBEDTLS_GCM_ALT*/
    #include"gcm_alt.h"
    #endif/*!MBEDTLS_GCM_ALT*/

    voidmbedtls_gcm_init(mbedtls_gcm_context*ctx);

    intmbedtls_gcm_setkey(mbedtls_gcm_context*ctx,
    mbedtls_cipher_id_tcipher,
    constunsignedchar*key,
    unsignedintkeybits);

    intmbedtls_gcm_crypt_and_tag(mbedtls_gcm_context*ctx,
    intmode,
    size_tlength,
    constunsignedchar*iv,
    size_tiv_len,
    constunsignedchar*add,
    size_tadd_len,
    constunsignedchar*input,
    unsignedchar*output,
    size_ttag_len,
    unsignedchar*tag);

    intmbedtls_gcm_auth_decrypt(mbedtls_gcm_context*ctx,
    size_tlength,
    constunsignedchar*iv,
    size_tiv_len,
    constunsignedchar*add,
    size_tadd_len,
    constunsignedchar*tag,
    size_ttag_len,
    constunsignedchar*input,
    unsignedchar*output);

    intmbedtls_gcm_starts(mbedtls_gcm_context*ctx,
    intmode,
    constunsignedchar*iv,
    size_tiv_len,
    constunsignedchar*add,
    size_tadd_len);

    intmbedtls_gcm_update(mbedtls_gcm_context*ctx,
    size_tlength,
    constunsignedchar*input,
    unsignedchar*output);

    intmbedtls_gcm_finish(mbedtls_gcm_context*ctx,
    unsignedchar*tag,
    size_ttag_len);

    voidmbedtls_gcm_free(mbedtls_gcm_context*ctx);

    #ifdefined(MBEDTLS_SELF_TEST)

    intmbedtls_gcm_self_test(intverbose);

    #endif/*MBEDTLS_SELF_TEST*/

    #ifdef__cplusplus
    }
    #endif

    #endif/*gcm.h*/