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

Data Structures
struct	mbedtls_ccm_context
	The CCM context-type definition. More...
Typedefs
typedef struct mbedtls_ccm_context	mbedtls_ccm_context
	The CCM context-type definition.
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 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.
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*.
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.
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.
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.

Typedef Documentation

typedef struct mbedtls_ccm_context mbedtls_ccm_context

The CCM context-type definition.

The CCM context is passed to the APIs called.

Function Documentation

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 (nonce).
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.
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 authentication field.
tag_len	The length of the authentication field 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.

This function performs a CCM authenticated decryption of a buffer.

Parameters:

ctx	CCM context
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	buffer holding the tag
tag_len	length of the tag

Returns:: 0 if successful and authenticated, MBEDTLS_ERR_CCM_AUTH_FAILED if tag does not match

Definition at line 105 of file ccm_alt.c.

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.
length	The length of the input data in Bytes.
iv	Initialization vector (nonce).
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.
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 authentication field.
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.

This function encrypts a buffer using CCM.

Parameters:

ctx	CCM context
length	length of the input data in bytes
iv	nonce (initialization vector)
iv_len	length of IV in bytes must be 2, 3, 4, 5, 6, 7 or 8
add	additional data
add_len	length of additional data in bytes must be less than 2^16 - 2^8
input	buffer holding the input data
output	buffer for holding the output data must be at least 'length' bytes wide
tag	buffer for holding the tag
tag_len	length of the tag to generate in bytes must be 4, 6, 8, 10, 14 or 16

Note:: The tag is written to a separate buffer. To get the tag concatenated with the output as in the CCM spec, use tag = output + length and make sure the output buffer is at least length + tag_len wide.

Returns:: 0 if successful

Definition at line 68 of file ccm_alt.c.

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.

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

Parameters:

ctx	CCM context to free

Definition at line 38 of file ccm_alt.c.

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 function initializes the specified CCM context, to make references valid, and prepare the context for mbedtls_ccm_setkey() or mbedtls_ccm_free().

Parameters:

ctx	CCM context to initialize

Definition at line 33 of file ccm_alt.c.

int mbedtls_ccm_self_test ( int verbose )

The CCM checkup routine.

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

Definition at line 427 of file ccm.c.

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.; A CCM or cipher-specific error code on failure.

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

Parameters:

ctx	CCM context to be initialized
cipher	cipher to use (a 128-bit block cipher)
key	encryption key
keybits	key size in bits (must be acceptable by the cipher)

Returns:: 0 if successful, or a cipher specific error code

Definition at line 43 of file ccm_alt.c.

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.
length	The length of the input data in Bytes.
iv	Initialization vector (nonce).
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.
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 authentication field.
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 no 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.

Definition at line 333 of file ccm.c.

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.
length	The length of the input data in Bytes.
iv	Initialization vector (nonce).
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.
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 authentication field.
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.

Definition at line 307 of file ccm.c.

Type:	Program
Created:	12 Feb 2019
Imports:	15
Forks:	0
Commits:	7
Dependents:	0
Dependencies:	3
Followers:	1

Important changes to repositories hosted on mbed.com

ccm.h File Reference

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

ccm.h File Reference

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning