Loading...
Searching...
No Matches
ccm.h File Reference

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

`#include "mbedtls/private_access.h"`
`#include "mbedtls/build_info.h"`
`#include "mbedtls/cipher.h"`
Include dependency graph for ccm.h:
This graph shows which files directly or indirectly include this file:

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_CCM_DECRYPT 0
#define | MBEDTLS_CCM_ENCRYPT 1
#define | MBEDTLS_CCM_STAR_DECRYPT 2
#define | MBEDTLS_CCM_STAR_ENCRYPT 3
#define | MBEDTLS_ERR_CCM_BAD_INPUT -0x000D
#define | MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F

## Typedefs

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

## 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().
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.
void | mbedtls_ccm_free (mbedtls_ccm_context *ctx)
| This function releases and clears the specified CCM context and underlying cipher sub-context.
int | mbedtls_ccm_encrypt_and_tag (mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *ad, size_t ad_len, const unsigned char *input, unsigned char *output, unsigned char *tag, size_t tag_len)
| This function encrypts a buffer using CCM.
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 *ad, size_t ad_len, const unsigned char *input, unsigned char *output, unsigned char *tag, size_t tag_len)
| This function encrypts a buffer using CCM*.
int | mbedtls_ccm_auth_decrypt (mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *ad, size_t ad_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.
int | mbedtls_ccm_star_auth_decrypt (mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *ad, size_t ad_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.
int | mbedtls_ccm_starts (mbedtls_ccm_context *ctx, int mode, const unsigned char *iv, size_t iv_len)
| This function starts a CCM encryption or decryption operation.
int | mbedtls_ccm_set_lengths (mbedtls_ccm_context *ctx, size_t total_ad_len, size_t plaintext_len, size_t tag_len)
| This function declares the lengths of the message and additional data for a CCM encryption or decryption operation.
int | mbedtls_ccm_update_ad (mbedtls_ccm_context *ctx, const unsigned char *ad, size_t ad_len)
| This function feeds an input buffer as associated data (authenticated but not encrypted data) in a CCM encryption or decryption operation.
int | mbedtls_ccm_update (mbedtls_ccm_context *ctx, const unsigned char *input, size_t input_len, unsigned char *output, size_t output_size, size_t *output_len)
| This function feeds an input buffer into an ongoing CCM encryption or decryption operation.
int | mbedtls_ccm_finish (mbedtls_ccm_context *ctx, unsigned char *tag, size_t tag_len)
| This function finishes the CCM operation and generates the authentication tag.
int | mbedtls_ccm_self_test (int verbose)
| The CCM checkup routine.

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

#define MBEDTLS_CCM_DECRYPT 0

Definition at line 47 of file ccm.h.

## MBEDTLS_CCM_ENCRYPT

#define MBEDTLS_CCM_ENCRYPT 1

Definition at line 48 of file ccm.h.

## MBEDTLS_CCM_STAR_DECRYPT

#define MBEDTLS_CCM_STAR_DECRYPT 2

Definition at line 49 of file ccm.h.

## MBEDTLS_CCM_STAR_ENCRYPT

#define MBEDTLS_CCM_STAR_ENCRYPT 3

Definition at line 50 of file ccm.h.

## MBEDTLS_ERR_CCM_AUTH_FAILED

#define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F

Authenticated decryption failed.

Definition at line 55 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 53 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 * | ad,
|  | size_t | ad_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`.
  ad | The additional data field. This must be a readable buffer of at least that `ad_len` Bytes..
  ad_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 * | ad,
|  | size_t | ad_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`.
  ad | The additional data field. If `ad_len` is greater than zero, `ad` must be a readable buffer of at least that length.
  ad_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 writable 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_finish()

int mbedtls_ccm_finish | ( | mbedtls_ccm_context * | ctx,
|  | unsigned char * | tag,
|  | size_t | tag_len )

This function finishes the CCM operation and generates the authentication tag.

It wraps up the CCM stream, and generates the tag. The tag can have a maximum length of 16 Bytes.

Note
  This function is not implemented in Mbed TLS yet.

Parameters

  ctx | The CCM context. This must have been started with mbedtls_ccm_starts() and the lengths of the message and additional data must have been declared with mbedtls_ccm_set_lengths().
  tag | The buffer for holding the tag. If `tag_len` is greater than zero, this must be a writable buffer of at least `tag_len` Bytes.
  tag_len | The length of the tag. Must match the tag length passed to mbedtls_ccm_set_lengths() function.

Returns
  `0` on success.
  MBEDTLS_ERR_CCM_BAD_INPUT on failure: `ctx` is in an invalid state, invalid value of `tag_len`, the total amount of additional data passed to mbedtls_ccm_update_ad() was lower than the total length of additional data `total_ad_len` passed to mbedtls_ccm_set_lengths(), the total amount of input data passed to mbedtls_ccm_update() was lower than the plaintext length `plaintext_len` passed to mbedtls_ccm_set_lengths().

## 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_set_lengths()

int mbedtls_ccm_set_lengths | ( | mbedtls_ccm_context * | ctx,
|  | size_t | total_ad_len,
|  | size_t | plaintext_len,
|  | size_t | tag_len )

This function declares the lengths of the message and additional data for a CCM encryption or decryption operation.

This function and mbedtls_ccm_starts() must be called before calling mbedtls_ccm_update_ad() or mbedtls_ccm_update(). This function can be called before or after mbedtls_ccm_starts().

Note
  This function is not implemented in Mbed TLS yet.

Parameters

  ctx | The CCM context. This must be initialized.
  total_ad_len | The total length of additional data in bytes. This must be less than 2^16 - 2^8.
  plaintext_len | The length in bytes of the plaintext to encrypt or result of the decryption (thus not encompassing the additional data that are not encrypted).
  tag_len | The length of the tag to generate in Bytes: 4, 6, 8, 10, 12, 14 or 16. For CCM*, zero is also valid.

Returns
  `0` on success.
  MBEDTLS_ERR_CCM_BAD_INPUT on failure: `ctx` is in an invalid state, `total_ad_len` is greater than `0xFF00`.

## 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 * | ad,
|  | size_t | ad_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. For tag length = 0, input length is ignored.
  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`.
  ad | The additional data field. This must be a readable buffer of at least that `ad_len` Bytes.
  ad_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 * | ad,
|  | size_t | ad_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. For tag length = 0, input length is ignored.
  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`.
  ad | The additional data field. This must be a readable buffer of at least `ad_len` Bytes.
  ad_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 writable 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.

## mbedtls_ccm_starts()

int mbedtls_ccm_starts | ( | mbedtls_ccm_context * | ctx,
|  | int | mode,
|  | const unsigned char * | iv,
|  | size_t | iv_len )

This function starts a CCM encryption or decryption operation.

This function and mbedtls_ccm_set_lengths() must be called before calling mbedtls_ccm_update_ad() or mbedtls_ccm_update(). This function can be called before or after mbedtls_ccm_set_lengths().

Note
  This function is not implemented in Mbed TLS yet.

Parameters

  ctx | The CCM context. This must be initialized.
  mode | The operation to perform: MBEDTLS_CCM_ENCRYPT or MBEDTLS_CCM_DECRYPT or MBEDTLS_CCM_STAR_ENCRYPT or MBEDTLS_CCM_STAR_DECRYPT.
  iv | The initialization vector. 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`.

Returns
  `0` on success.
  MBEDTLS_ERR_CCM_BAD_INPUT on failure: `ctx` is in an invalid state, `mode` is invalid, `iv_len` is invalid (lower than `7` or greater than `13`).

## mbedtls_ccm_update()

int mbedtls_ccm_update | ( | mbedtls_ccm_context * | ctx,
|  | const unsigned char * | input,
|  | size_t | input_len,
|  | unsigned char * | output,
|  | size_t | output_size,
|  | size_t * | output_len )

This function feeds an input buffer into an ongoing CCM 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_ccm_finish(). The lengths `input_len` of the data parts should eventually add up exactly to the plaintext length `plaintext_len` passed to mbedtls_ccm_set_lengths().

This function may produce output in one of the following ways:

- Immediate output: the output length is always equal to the input length.
- Buffered output: except for the last part of input data, the output consists of a whole number of 16-byte blocks. If the total input length so far (not including associated data) is 16 * B + A with A < 16 then the total output length is 16 * B. For the last part of input data, the output length is equal to the input length plus the number of bytes (A) buffered in the previous call to the function (if any). The function uses the plaintext length `plaintext_len` passed to mbedtls_ccm_set_lengths() to detect the last part of input data.

In particular:

- It is always correct to call this function with `output_size` >= `input_len` + 15.
- If `input_len` is a multiple of 16 for all the calls to this function during an operation (not necessary for the last one) then it is correct to use `output_size` =`input_len`.

Note
  This function is not implemented in Mbed TLS yet.

Parameters

  ctx | The CCM context. This must have been started with mbedtls_ccm_starts() and the lengths of the message and additional data must have been declared with mbedtls_ccm_set_lengths().
  input | The buffer holding the input data. If `input_len` is greater than zero, this must be a readable buffer of at least `input_len` bytes.
  input_len | 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 at least `output_size` bytes.
  output_size | The size of the output buffer in bytes. See the function description regarding the output size.
  output_len | On success, `*output_len` contains the actual length of the output written in `output`. On failure, the content of `*output_len` is unspecified.

Returns
  `0` on success.
  MBEDTLS_ERR_CCM_BAD_INPUT on failure: `ctx` is in an invalid state, total input length too long, or `output_size` too small.

## mbedtls_ccm_update_ad()

int mbedtls_ccm_update_ad | ( | mbedtls_ccm_context * | ctx,
|  | const unsigned char * | ad,
|  | size_t | ad_len )

This function feeds an input buffer as associated data (authenticated but not encrypted data) in a CCM encryption or decryption operation.

You may call this function zero, one or more times to pass successive parts of the additional data. The lengths `ad_len` of the data parts should eventually add up exactly to the total length of additional data `total_ad_len` passed to mbedtls_ccm_set_lengths(). You may not call this function after calling mbedtls_ccm_update().

Note
  This function is not implemented in Mbed TLS yet.

Parameters

  ctx | The CCM context. This must have been started with mbedtls_ccm_starts(), the lengths of the message and additional data must have been declared with mbedtls_ccm_set_lengths() and this must not have yet received any input with mbedtls_ccm_update().
  ad | The buffer holding the additional data, or `NULL` if `ad_len` is `0`.
  ad_len | The length of the additional data. If `0`, `ad` may be `NULL`.

Returns
  `0` on success.
  MBEDTLS_ERR_CCM_BAD_INPUT on failure: `ctx` is in an invalid state, total input length too long.