gcm.h File Reference
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..
More...
#include "cipher.h"
#include <stdint.h>
Go to the source code of this file.
Data Structures |
struct | mbedtls_gcm_context |
| The GCM context structure. More...
|
Defines |
#define | MBEDTLS_GCM_ENCRYPT 1 |
#define | MBEDTLS_GCM_DECRYPT 0 |
#define | MBEDTLS_ERR_GCM_AUTH_FAILED -0x0012 |
#define | MBEDTLS_ERR_GCM_HW_ACCEL_FAILED -0x0013 |
#define | MBEDTLS_ERR_GCM_BAD_INPUT -0x0014 |
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
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.
Definition in file gcm.h.
Define Documentation
#define MBEDTLS_ERR_GCM_AUTH_FAILED -0x0012 |
Authenticated decryption failed.
Definition at line 41 of file gcm.h.
#define MBEDTLS_ERR_GCM_BAD_INPUT -0x0014 |
Bad input parameters to function.
Definition at line 43 of file gcm.h.
#define MBEDTLS_ERR_GCM_HW_ACCEL_FAILED -0x0013 |
GCM hardware accelerator failed.
Definition at line 42 of file gcm.h.
#define MBEDTLS_GCM_DECRYPT 0 |
Definition at line 39 of file gcm.h.
#define MBEDTLS_GCM_ENCRYPT 1 |
Definition at line 38 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. |
| length | The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish(). |
| iv | The initialization vector. |
| iv_len | The length of the IV. |
| add | The buffer holding the additional data. |
| add_len | The length of the additional data. |
| tag | The buffer holding the tag. |
| tag_len | The length of the tag. |
| input | The buffer holding the input data. |
| output | The 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:
-
| ctx | The GCM context to use for encryption or decryption. |
| mode | The operation to perform: MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT. |
| length | The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish(). |
| iv | The initialization vector. |
| iv_len | The length of the IV. |
| add | The buffer holding the additional data. |
| add_len | The length of the additional data. |
| input | The buffer holding the input data. |
| output | The buffer for holding the output data. |
| tag_len | The length of the tag to generate. |
| tag | The buffer for holding the tag. |
- Returns:
0
on success.
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. |
| tag | The buffer for holding the tag. |
| tag_len | The length of the tag to generate. Must be at least four. |
- Returns:
0
on success, or MBEDTLS_ERR_GCM_BAD_INPUT on failure.
This function clears a GCM context and the underlying cipher sub-context.
- Parameters:
-
| ctx | The GCM context to clear. |
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. |
int mbedtls_gcm_self_test |
( |
int |
verbose |
) |
|
The GCM checkup routine.
- Returns:
0
on success, or 1
on failure.
This function associates a GCM context with a cipher algorithm and a key.
- Parameters:
-
| ctx | The GCM context to initialize. |
| cipher | The 128-bit block cipher to use. |
| key | The encryption key. |
| keybits | The 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:
-
| ctx | The GCM context. |
| mode | The operation to perform: MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT. |
| iv | The initialization vector. |
| 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 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:
-
| ctx | The GCM context. |
| 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. |
| output | The buffer for holding the output data. |
- Returns:
0
on success, or MBEDTLS_ERR_GCM_BAD_INPUT on failure.