cmac.h File Reference

This file contains CMAC definitions and functions. More...

#include "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include "mbedtls/cipher.h"

Include dependency graph for cmac.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	mbedtls_cmac_context_t

Macros
#define	MBEDTLS_AES_BLOCK_SIZE   16
#define	MBEDTLS_DES3_BLOCK_SIZE   8
#define	MBEDTLS_CMAC_MAX_BLOCK_SIZE   8
#define	MBEDTLS_CIPHER_BLKSIZE_MAX   MBEDTLS_MAX_BLOCK_LENGTH

Functions
int	mbedtls_cipher_cmac_starts (mbedtls_cipher_context_t *ctx, const unsigned char *key, size_t keybits)
	This function starts a new CMAC computation by setting the CMAC key, and preparing to authenticate the input data. It must be called with an initialized cipher context.
int	mbedtls_cipher_cmac_update (mbedtls_cipher_context_t *ctx, const unsigned char *input, size_t ilen)
	This function feeds an input buffer into an ongoing CMAC computation.
int	mbedtls_cipher_cmac_finish (mbedtls_cipher_context_t *ctx, unsigned char *output)
	This function finishes an ongoing CMAC operation, and writes the result to the output buffer.
int	mbedtls_cipher_cmac_reset (mbedtls_cipher_context_t *ctx)
	This function starts a new CMAC operation with the same key as the previous one.
int	mbedtls_cipher_cmac (const mbedtls_cipher_info_t *cipher_info, const unsigned char *key, size_t keylen, const unsigned char *input, size_t ilen, unsigned char *output)
	This function calculates the full generic CMAC on the input buffer with the provided key.

Detailed Description

This file contains CMAC definitions and functions.

The Cipher-based Message Authentication Code (CMAC) Mode for Authentication is defined in RFC-4493: The AES-CMAC Algorithm. It is supported with AES and DES.

Macro Definition Documentation

MBEDTLS_AES_BLOCK_SIZE

#define MBEDTLS_AES_BLOCK_SIZE   16

MBEDTLS_CIPHER_BLKSIZE_MAX

#define MBEDTLS_CIPHER_BLKSIZE_MAX   MBEDTLS_MAX_BLOCK_LENGTH

The longest block supported by the cipher module.

Deprecated:

For the maximum block size of a cipher supported by the CMAC module, use MBEDTLS_CMAC_MAX_BLOCK_SIZE. For the maximum block size of a cipher supported by the cipher module, use MBEDTLS_MAX_BLOCK_LENGTH.

MBEDTLS_CMAC_MAX_BLOCK_SIZE

#define MBEDTLS_CMAC_MAX_BLOCK_SIZE   8

The longest block used by CMAC is that of 3DES.

MBEDTLS_DES3_BLOCK_SIZE

#define MBEDTLS_DES3_BLOCK_SIZE   8

Function Documentation

mbedtls_cipher_cmac()

int mbedtls_cipher_cmac	(	const mbedtls_cipher_info_t *	cipher_info,
		const unsigned char *	key,
		size_t	keylen,
		const unsigned char *	input,
		size_t	ilen,
		unsigned char *	output
	)

This function calculates the full generic CMAC on the input buffer with the provided key.

The function allocates the context, performs the calculation, and frees the context.

The CMAC result is calculated as output = generic CMAC(cmac key, input buffer).

Note

When the CMAC implementation is supplied by an alternate implementation (through MBEDTLS_CMAC_ALT), some ciphers may not be supported by that implementation, and thus return an error. Alternate implementations must support AES-128 and AES-256, and may support AES-192 and 3DES.

Parameters

cipher_info	The cipher information.
key	The CMAC key.
keylen	The length of the CMAC key in bits.
input	The buffer holding the input data.
ilen	The length of the input data.
output	The buffer for the generic CMAC result.

Returns

0 on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification fails.

mbedtls_cipher_cmac_finish()

int mbedtls_cipher_cmac_finish	(	mbedtls_cipher_context_t *	ctx,
		unsigned char *	output
	)

This function finishes an ongoing CMAC operation, and writes the result to the output buffer.

It should be followed either by mbedtls_cipher_cmac_reset(), which starts another CMAC operation with the same key, or mbedtls_cipher_free(), which clears the cipher context.

Parameters

ctx	The cipher context used for the CMAC operation.
output	The output buffer for the CMAC checksum result.

Returns

0 on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification fails.

mbedtls_cipher_cmac_reset()

int mbedtls_cipher_cmac_reset

(

mbedtls_cipher_context_t *

ctx

)

This function starts a new CMAC operation with the same key as the previous one.

It should be called after finishing the previous CMAC operation with mbedtls_cipher_cmac_finish(). After calling this function, call mbedtls_cipher_cmac_update() to supply the new CMAC operation with data.

Parameters

ctx	The cipher context used for the CMAC operation.

Returns

0 on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification fails.

mbedtls_cipher_cmac_starts()

int mbedtls_cipher_cmac_starts	(	mbedtls_cipher_context_t *	ctx,
		const unsigned char *	key,
		size_t	keybits
	)

This function starts a new CMAC computation by setting the CMAC key, and preparing to authenticate the input data. It must be called with an initialized cipher context.

Once this function has completed, data can be supplied to the CMAC computation by calling mbedtls_cipher_cmac_update().

To start a CMAC computation using the same key as a previous CMAC computation, use mbedtls_cipher_cmac_finish().

Note

When the CMAC implementation is supplied by an alternate implementation (through MBEDTLS_CMAC_ALT), some ciphers may not be supported by that implementation, and thus return an error. Alternate implementations must support AES-128 and AES-256, and may support AES-192 and 3DES.

Parameters

ctx	The cipher context used for the CMAC operation, initialized as one of the following types: MBEDTLS_CIPHER_AES_128_ECB, MBEDTLS_CIPHER_AES_192_ECB, MBEDTLS_CIPHER_AES_256_ECB, or MBEDTLS_CIPHER_DES_EDE3_ECB.
key	The CMAC key.
keybits	The length of the CMAC key in bits. Must be supported by the cipher.

Returns

0 on success.

A cipher-specific error code on failure.

mbedtls_cipher_cmac_update()

int mbedtls_cipher_cmac_update	(	mbedtls_cipher_context_t *	ctx,
		const unsigned char *	input,
		size_t	ilen
	)

This function feeds an input buffer into an ongoing CMAC computation.

The CMAC computation must have previously been started by calling mbedtls_cipher_cmac_starts() or mbedtls_cipher_cmac_reset().

Call this function as many times as needed to input the data to be authenticated. Once all of the required data has been input, call mbedtls_cipher_cmac_finish() to obtain the result of the CMAC operation.

Parameters

ctx	The cipher context used for the CMAC operation.
input	The buffer holding the input data.
ilen	The length of the input data.

Returns

0 on success.

MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification fails.