File ccm.h

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.

Defines

MBEDTLS_ERR_CCM_BAD_INPUT: Bad input parameters to the function.

MBEDTLS_ERR_CCM_AUTH_FAILED: Authenticated decryption failed.

MBEDTLS_ERR_CCM_HW_ACCEL_FAILED: CCM hardware accelerator failed.

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().

Parameters: ctx – The CCM context to initialize. This must not be NULL.

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.

Returns

A CCM or cipher-specific error code on failure.

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.

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

Returns

A CCM or cipher-specific error code on failure.

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.

Note

When using this function in a variable tag length context, the tag length has to be encoded into the iv passed to this function.

Warning

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

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

Returns

0 on success.

Returns

A CCM or cipher-specific error code on failure.

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.

Returns

MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.

Returns

A cipher-specific error code on calculation failure.

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.)

Warning

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

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.

Returns

0 on success.

Returns

MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.

Returns

A cipher-specific error code on calculation failure.

int mbedtls_ccm_self_test(int verbose)

The CCM checkup routine.

Returns: 0 on success.
Returns: 1 on failure.