ccm.h File Reference

CCM combines Counter mode encryption with CBC-MAC authentication for 128-bit block ciphers. More...

`#include "cipher.h"`
Include dependency graph for ccm.h:

Go to the source code of this file.

## Data Structures

struct | mbedtls_ccm_context
| The CCM context-type definition. The CCM context is passed to the APIs called. More...

## Macros

#define | MBEDTLS_ERR_CCM_BAD_INPUT -0x000D
#define | MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F
#define | MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011

## Functions

void | mbedtls_ccm_init (mbedtls_ccm_context *ctx)
| This function initializes the specified CCM context, to make references valid, and prepare the context for mbedtls_ccm_setkey() or mbedtls_ccm_free(). More...
int | mbedtls_ccm_setkey (mbedtls_ccm_context *ctx, mbedtls_cipher_id_t cipher, const unsigned char *key, unsigned int keybits)
| This function initializes the CCM context set in the `ctx` parameter and sets the encryption key. More...
void | mbedtls_ccm_free (mbedtls_ccm_context *ctx)
| This function releases and clears the specified CCM context and underlying cipher sub-context. More...
int | mbedtls_ccm_encrypt_and_tag (mbedtls_ccm_context *ctx, 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, unsigned char *tag, size_t tag_len)
| This function encrypts a buffer using CCM. More...
int | mbedtls_ccm_auth_decrypt (mbedtls_ccm_context *ctx, 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, const unsigned char *tag, size_t tag_len)
| This function performs a CCM authenticated decryption of a buffer. More...
int | mbedtls_ccm_self_test (int verbose)
| The CCM checkup routine. More...

## Detailed Description

CCM combines Counter mode encryption with CBC-MAC authentication for 128-bit block ciphers.

Input to CCM includes the following elements:

- Payload - data that is both authenticated and encrypted.
- Associated data (Adata) - data that is authenticated but not encrypted, For example, a header.
- Nonce - A unique value that is assigned to the payload and the associated data.

Definition in file ccm.h.

## Macro Definition Documentation

## MBEDTLS_ERR_CCM_AUTH_FAILED

#define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F

Authenticated decryption failed.

Definition at line 40 of file ccm.h.

## MBEDTLS_ERR_CCM_BAD_INPUT

#define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D

Bad input parameters to the function.

Definition at line 39 of file ccm.h.

## MBEDTLS_ERR_CCM_HW_ACCEL_FAILED

#define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011

CCM hardware accelerator failed.

Definition at line 41 of file ccm.h.

## Function Documentation

## mbedtls_ccm_auth_decrypt()

int mbedtls_ccm_auth_decrypt | ( | mbedtls_ccm_context * | ctx,
|  | 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,
|  | const unsigned char * | tag,
|  | size_t | tag_len
| ) |  |

This function performs a CCM authenticated decryption of a buffer.

Parameters

  ctx | The CCM context to use for decryption.
  length | The length of the input data in Bytes.
  iv | Initialization vector.
  iv_len | The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
  add | The additional data field.
  add_len | The length of additional data in Bytes. Must be less than 2^16 - 2^8.
  input | The buffer holding the input data.
  output | The buffer holding the output data. Must be at least `length` Bytes wide.
  tag | The buffer holding the tag.
  tag_len | The length of the tag in Bytes. 4, 6, 8, 10, 12, 14 or 16.

Returns
  0 if successful and authenticated, or MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.

## mbedtls_ccm_encrypt_and_tag()

int mbedtls_ccm_encrypt_and_tag | ( | mbedtls_ccm_context * | ctx,
|  | 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,
|  | unsigned char * | tag,
|  | size_t | tag_len
| ) |  |

This function encrypts a buffer using CCM.

Parameters

  ctx | The CCM context to use for encryption.
  length | The length of the input data in Bytes.
  iv | Initialization vector (nonce).
  iv_len | The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
  add | The additional data field.
  add_len | The length of additional data in Bytes. Must be less than 2^16 - 2^8.
  input | The buffer holding the input data.
  output | The buffer holding the output data. Must be at least `length` Bytes wide.
  tag | The buffer holding the tag.
  tag_len | The length of the tag to generate in Bytes: 4, 6, 8, 10, 12, 14 or 16.

Note
  The tag is written to a separate buffer. To concatenate the `tag` with the `output`, as done in RFC-3610: Counter with CBC-MAC (CCM), use `tag` = `output` + `length`, and make sure that the output buffer is at least `length` + `tag_len` wide.

Returns
  `0` on success.

## mbedtls_ccm_free()

void mbedtls_ccm_free | ( | mbedtls_ccm_context * | ctx | ) |

This function releases and clears the specified CCM context and underlying cipher sub-context.

Parameters

  ctx | The CCM context to clear.

## mbedtls_ccm_init()

void mbedtls_ccm_init | ( | mbedtls_ccm_context * | ctx | ) |

This function initializes the specified CCM context, to make references valid, and prepare the context for mbedtls_ccm_setkey() or mbedtls_ccm_free().

Parameters

  ctx | The CCM context to initialize.

## mbedtls_ccm_self_test()

int mbedtls_ccm_self_test | ( | int | verbose | ) |

The CCM checkup routine.

Returns
  `0` on success, or `1` on failure.

## mbedtls_ccm_setkey()

int mbedtls_ccm_setkey | ( | mbedtls_ccm_context * | ctx,
|  | mbedtls_cipher_id_t | cipher,
|  | const unsigned char * | key,
|  | unsigned int | keybits
| ) |  |

This function initializes the CCM context set in the `ctx` parameter and sets the encryption key.

Parameters

  ctx | The CCM context to initialize.
  cipher | The 128-bit block cipher to use.
  key | The encryption key.
  keybits | The key size in bits. This must be acceptable by the cipher.

Returns
  `0` on success, or a cipher-specific error code.