mbed TLS v2.23.0: ccm.h File Reference

mbed TLS v2.23.0

Data Structures | Macros | Typedefs | Functions
ccm.h File Reference

This file provides an API for the CCM authenticated encryption mode for block ciphers. More...

`#include "mbedtls/config.h"`
`#include "mbedtls/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

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

## 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_star_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_star_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

This file provides an API for the CCM authenticated encryption mode for block ciphers.

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 of CCM: http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf RFC 3610 "Counter with CBC-MAC (CCM)"

Related: RFC 5116 "An Interface and Algorithms for Authenticated Encryption"

Definition of CCM*: IEEE 802.15.4 - IEEE Standard for Local and metropolitan area networks Integer representation is fixed most-significant-octet-first order and the representation of octets is most-significant-bit-first order. This is consistent with RFC 3610.

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 62 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 61 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 65 of file ccm.h.

## Typedef Documentation

## ◆ mbedtls_ccm_context

typedef struct mbedtls_ccm_context mbedtls_ccm_context

The CCM context-type definition. The CCM context is passed to the APIs called.

## 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. This must be initialized and bound to a key.
  length | The length of the input data in Bytes.
  iv | The initialization vector (nonce). This must be a readable buffer of at least `iv_len` Bytes.
  iv_len | The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, or 13. The length L of the message length field is 15 - `iv_len`.
  add | The additional data field. This must be a readable buffer of at least that `add_len` Bytes..
  add_len | The length of additional data in Bytes. This must be less than 2^16 - 2^8.
  input | The buffer holding the input data. If `length` is greater than zero, `input` must be a readable buffer of at least that length.
  output | The buffer holding the output data. If `length` is greater than zero, `output` must be a writable buffer of at least that length.
  tag | The buffer holding the authentication field. This must be a readable buffer of at least `tag_len` Bytes.
  tag_len | The length of the authentication field to generate in Bytes: 4, 6, 8, 10, 12, 14 or 16.

Returns
  `0` on success. This indicates that the message is authentic.
  MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
  A cipher-specific error code on calculation failure.

## ◆ 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.

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.

Parameters

  ctx | The CCM context to use for encryption. This must be initialized and bound to a key.
  length | The length of the input data in Bytes.
  iv | The initialization vector (nonce). This must be a readable buffer of at least `iv_len` Bytes.
  iv_len | The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, or 13. The length L of the message length field is 15 - `iv_len`.
  add | The additional data field. If `add_len` is greater than zero, `add` must be a readable buffer of at least that length.
  add_len | The length of additional data in Bytes. This must be less than `2^16 - 2^8`.
  input | The buffer holding the input data. If `length` is greater than zero, `input` must be a readable buffer of at least that length.
  output | The buffer holding the output data. If `length` is greater than zero, `output` must be a writable buffer of at least that length.
  tag | The buffer holding the authentication field. This must be a readable buffer of at least `tag_len` Bytes.
  tag_len | The length of the authentication field to generate in Bytes: 4, 6, 8, 10, 12, 14 or 16.

Returns
  `0` on success.
  A CCM or cipher-specific error code on failure.

## ◆ 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. If this is `NULL`, the function has no effect. Otherwise, this must be initialized.

## ◆ 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. This must not be `NULL`.

## ◆ mbedtls_ccm_self_test()

int mbedtls_ccm_self_test | ( | int | verbose | ) |

The CCM checkup routine.

Returns
  `0` on success.
  `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. This must be an initialized context.
  cipher | The 128-bit block cipher to use.
  key | The encryption key. This must not be `NULL`.
  keybits | The key size in bits. This must be acceptable by the cipher.

Returns
  `0` on success.
  A CCM or cipher-specific error code on failure.

## ◆ mbedtls_ccm_star_auth_decrypt()

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

Note
  When using this function in a variable tag length context, the tag length has to be decoded from `iv` and passed to this function as `tag_len`. (`tag` needs to be adjusted accordingly.)

Parameters

  ctx | The CCM context to use for decryption. This must be initialized and bound to a key.
  length | The length of the input data in Bytes.
  iv | The initialization vector (nonce). This must be a readable buffer of at least `iv_len` Bytes.
  iv_len | The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, or 13. The length L of the message length field is 15 - `iv_len`.
  add | The additional data field. This must be a readable buffer of at least that `add_len` Bytes.
  add_len | The length of additional data in Bytes. This must be less than 2^16 - 2^8.
  input | The buffer holding the input data. If `length` is greater than zero, `input` must be a readable buffer of at least that length.
  output | The buffer holding the output data. If `length` is greater than zero, `output` must be a writable buffer of at least that length.
  tag | The buffer holding the authentication field. This must be a readable buffer of at least `tag_len` Bytes.
  tag_len | The length of the authentication field in Bytes. 0, 4, 6, 8, 10, 12, 14 or 16.

Warning
  Passing `0` as `tag_len` means that the message is nos longer authenticated.

Returns
  `0` on success.
  MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
  A cipher-specific error code on calculation failure.

## ◆ mbedtls_ccm_star_encrypt_and_tag()

int mbedtls_ccm_star_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*.

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.
  When using this function in a variable tag length context, the tag length has to be encoded into the `iv` passed to this function.

Parameters

  ctx | The CCM context to use for encryption. This must be initialized and bound to a key.
  length | The length of the input data in Bytes.
  iv | The initialization vector (nonce). This must be a readable buffer of at least `iv_len` Bytes.
  iv_len | The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12, or 13. The length L of the message length field is 15 - `iv_len`.
  add | The additional data field. This must be a readable buffer of at least `add_len` Bytes.
  add_len | The length of additional data in Bytes. This must be less than 2^16 - 2^8.
  input | The buffer holding the input data. If `length` is greater than zero, `input` must be a readable buffer of at least that length.
  output | The buffer holding the output data. If `length` is greater than zero, `output` must be a writable buffer of at least that length.
  tag | The buffer holding the authentication field. This must be a readable buffer of at least `tag_len` Bytes.
  tag_len | The length of the authentication field to generate in Bytes: 0, 4, 6, 8, 10, 12, 14 or 16.

Warning
  Passing `0` as `tag_len` means that the message is no longer authenticated.

Returns
  `0` on success.
  A CCM or cipher-specific error code on failure.