gcm.h File Reference

Galois/Counter mode for 128-bit block ciphers. More...

`#include "cipher.h"`
`#include <stdint.h>`
Include dependency graph for gcm.h:

Go to the source code of this file.

## Data Structures

struct | mbedtls_gcm_context
| 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_BAD_INPUT -0x0014
| Bad input parameters to function. More...

## Functions

void | mbedtls_gcm_init (mbedtls_gcm_context *ctx)
| Initialize GCM context (just makes references valid) Makes the context ready 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)
| GCM initialization (encryption) 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)
| GCM buffer encryption/decryption using a block cipher. 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)
| GCM buffer authenticated decryption using a block cipher. 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)
| Generic GCM stream start function. More...
int | mbedtls_gcm_update (mbedtls_gcm_context *ctx, size_t length, const unsigned char *input, unsigned char *output)
| Generic GCM update function. More...
int | mbedtls_gcm_finish (mbedtls_gcm_context *ctx, unsigned char *tag, size_t tag_len)
| Generic GCM finalisation function. More...
void | mbedtls_gcm_free (mbedtls_gcm_context *ctx)
| Free a GCM context and underlying cipher sub-context. More...
int | mbedtls_gcm_self_test (int verbose)
| Checkup routine. More...

## Detailed Description

Galois/Counter mode for 128-bit block ciphers.

Copyright (C) 2006-2015, ARM Limited, All Rights Reserved SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file is part of mbed TLS (https://tls.mbed.org)

Definition in file gcm.h.

## Macro Definition Documentation

#define MBEDTLS_ERR_GCM_AUTH_FAILED -0x0012

Authenticated decryption failed.

Definition at line 33 of file gcm.h.

#define MBEDTLS_ERR_GCM_BAD_INPUT -0x0014

Bad input parameters to function.

Definition at line 34 of file gcm.h.

#define MBEDTLS_GCM_DECRYPT 0

Definition at line 31 of file gcm.h.

#define MBEDTLS_GCM_ENCRYPT 1

Definition at line 30 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
| ) |  |

GCM buffer authenticated decryption using a block cipher.

Note
  On decryption, the output buffer cannot be the same as input buffer. If buffers overlap, the output buffer must trail at least 8 bytes behind the input buffer.

Parameters

  ctx | GCM context
  length | length of the input data
  iv | initialization vector
  iv_len | length of IV
  add | additional data
  add_len | length of additional data
  tag | buffer holding the tag
  tag_len | length of the tag
  input | buffer holding the input data
  output | buffer for holding the output data

Returns
  0 if successful and authenticated, 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
| ) |  |

GCM buffer encryption/decryption using a block cipher.

Note
  On encryption, the output buffer can be the same as the input buffer. On decryption, the output buffer cannot be the same as input buffer. If buffers overlap, the output buffer must trail at least 8 bytes behind the input buffer.

Parameters

  ctx | GCM context
  mode | MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT
  length | length of the input data
  iv | initialization vector
  iv_len | length of IV
  add | additional data
  add_len | length of additional data
  input | buffer holding the input data
  output | buffer for holding the output data
  tag_len | length of the tag to generate
  tag | buffer for holding the tag

Returns
  0 if successful

int mbedtls_gcm_finish | ( | mbedtls_gcm_context * | ctx,
|  | unsigned char * | tag,
|  | size_t | tag_len
| ) |  |

Generic GCM finalisation function.

Wraps up the GCM stream and generates the tag. The tag can have a maximum length of 16 bytes.

Parameters

  ctx | GCM context
  tag | buffer for holding the tag (may be NULL if tag_len is 0)
  tag_len | length of the tag to generate

Returns
  0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT

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

Free a GCM context and underlying cipher sub-context.

Parameters

  ctx | GCM context to free

void mbedtls_gcm_init | ( | mbedtls_gcm_context * | ctx | ) |

Initialize GCM context (just makes references valid) Makes the context ready for mbedtls_gcm_setkey() or mbedtls_gcm_free().

Parameters

  ctx | GCM context to initialize

int mbedtls_gcm_self_test | ( | int | verbose | ) |

Checkup routine.

Returns
  0 if successful, or 1 if the test failed

int mbedtls_gcm_setkey | ( | mbedtls_gcm_context * | ctx,
|  | mbedtls_cipher_id_t | cipher,
|  | const unsigned char * | key,
|  | unsigned int | keybits
| ) |  |

GCM initialization (encryption)

Parameters

  ctx | GCM context to be initialized
  cipher | cipher to use (a 128-bit block cipher)
  key | encryption key
  keybits | must be 128, 192 or 256

Returns
  0 if successful, 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
| ) |  |

Generic GCM stream start function.

Parameters

  ctx | GCM context
  mode | MBEDTLS_GCM_ENCRYPT or MBEDTLS_GCM_DECRYPT
  iv | initialization vector
  iv_len | length of IV
  add | additional data (or NULL if length is 0)
  add_len | length of additional data

Returns
  0 if successful

int mbedtls_gcm_update | ( | mbedtls_gcm_context * | ctx,
|  | size_t | length,
|  | const unsigned char * | input,
|  | unsigned char * | output
| ) |  |

Generic GCM update function.

Encrypts/decrypts using the given GCM context. Expects input to be a multiple of 16 bytes! Only the last call before mbedtls_gcm_finish() can be less than 16 bytes!

Note
  On decryption, the output buffer cannot be the same as input buffer. If buffers overlap, the output buffer must trail at least 8 bytes behind the input buffer.

Parameters

  ctx | GCM context
  length | length of the input data
  input | buffer holding the input data
  output | buffer for holding the output data

Returns
  0 if successful or MBEDTLS_ERR_GCM_BAD_INPUT