mbed TLS v3.1.0
|
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"
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... | |
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.
#define MBEDTLS_ERR_GCM_AUTH_FAILED -0x0012 |
#define MBEDTLS_ERR_GCM_BAD_INPUT -0x0014 |
#define MBEDTLS_ERR_GCM_BUFFER_TOO_SMALL -0x0016 |
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.
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. 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.
ctx | The GCM context to use for encryption or decryption. This must be initialized. |
mode | The operation to perform:
|
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. 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.
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:
|
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. |
0
on success. 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.
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().
ctx | The GCM context to initialize. This must not be NULL . |
int mbedtls_gcm_self_test | ( | int | verbose | ) |
The GCM checkup routine.
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.
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:
|
0
on success. 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.
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. |
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:
In particular:
output_size
>= input_length
+ 15.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
.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. |
0
on success. 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().
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 . |
0
on success.