mbed TLS v2.9.0
Data Structures | Macros | Functions
ccm.h File Reference

This file provides an API for the CCM authenticated encryption mode for 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

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:

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 43 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 42 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 44 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
ctxThe CCM context to use for decryption.
lengthThe length of the input data in Bytes.
ivInitialization vector.
iv_lenThe length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
addThe additional data field.
add_lenThe length of additional data in Bytes. Must be less than 2^16 - 2^8.
inputThe buffer holding the input data.
outputThe buffer holding the output data. Must be at least length Bytes wide.
tagThe buffer holding the tag.
tag_lenThe length of the tag 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 *  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
ctxThe CCM context to use for encryption.
lengthThe length of the input data in Bytes.
ivInitialization vector (nonce).
iv_lenThe length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13.
addThe additional data field.
add_lenThe length of additional data in Bytes. Must be less than 2^16 - 2^8.
inputThe buffer holding the input data.
outputThe buffer holding the output data. Must be at least length Bytes wide.
tagThe buffer holding the tag.
tag_lenThe length of the tag 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_free()

void mbedtls_ccm_free ( mbedtls_ccm_context ctx)

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

Parameters
ctxThe 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
ctxThe CCM context to initialize.

§ mbedtls_ccm_self_test()

int mbedtls_ccm_self_test ( int  verbose)

The CCM checkup routine.

Returns
0 on success.
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
ctxThe CCM context to initialize.
cipherThe 128-bit block cipher to use.
keyThe encryption key.
keybitsThe key size in bits. This must be acceptable by the cipher.
Returns
0 on success.
A CCM or cipher-specific error code on failure.