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.