CMAC_INIT(3) | Library Functions Manual | CMAC_INIT(3)

# NAME

`CMAC_CTX_new`, `CMAC_Init`, `CMAC_Update`, `CMAC_Final`, `CMAC_CTX_copy`, `CMAC_CTX_get0_cipher_ctx`, `CMAC_CTX_cleanup`, `CMAC_CTX_free` — Cipher-based message authentication code

# SYNOPSIS

library “libcrypto”
`#include <openssl/cmac.h>`

CMAC_CTX *
`CMAC_CTX_new`(void);

int
`CMAC_Init`(CMAC_CTX *ctx, const void *key, size_t key_len, const EVP_CIPHER *cipher, ENGINE *engine);

int
`CMAC_Update`(CMAC_CTX *ctx, const void *in_data, size_t in_len);

int
`CMAC_Final`(CMAC_CTX *ctx, unsigned char *out_mac, size_t *out_len);

int
`CMAC_CTX_copy`(CMAC_CTX *out_ctx, CMAC_CTX *in_ctx);

EVP_CIPHER_CTX *
`CMAC_CTX_get0_cipher_ctx`(CMAC_CTX *ctx);

void
`CMAC_CTX_cleanup`(CMAC_CTX *ctx);

void
`CMAC_CTX_free`(CMAC_CTX *ctx);

# DESCRIPTION

CMAC is a message authentication code algorithm that can employ an arbitrary block cipher using a symmetric key.

The present manual page describes low-level functions implementing CMAC. Instead of using these functions directly, application programs normally call EVP_PKEY_new_CMAC_key(3) and then pass the resulting EVP_PKEY object to EVP_DigestSignInit(3).

The CMAC API is object-oriented. Calculating a message authentication code requires a CMAC_CTX object. Usually, the functions `CMAC_CTX_new`(), `CMAC_Init`(), `CMAC_Update`(), `CMAC_Final`(), and `CMAC_CTX_free`() need to be called in this order.

`CMAC_CTX_new`() allocates a new CMAC_CTX object, initializes the embedded EVP_CIPHER_CTX object, and marks the object itself as uninitialized.

`CMAC_Init`() selects the given block cipher for use by ctx. Functions to obtain suitable EVP_CIPHER objects are listed in the CIPHER LISTING section of the EVP_EncryptInit(3) manual page. Unless key is `NULL`, `CMAC_Init`() also initializes ctx for use with the given symmetric key that is key_len bytes long. In particular, it calculates and internally stores the two subkeys and initializes ctx for subsequently feeding in data with `CMAC_Update`(). The engine argument is ignored; passing `NULL` is recommended.

If ctx is already initialized, `CMAC_Init`() can be called again with key and cipher both set to `NULL` and key_len set to 0. In that case, any data already processed is discarded and ctx is re-initialized to start reading data anew.

`CMAC_Update`() processes in_len bytes of input data pointed to by in_data. Depending on the number of input bytes already cached in ctx, on in_len, and on the block size, this may encrypt zero or more blocks. Unless in_len is zero, this function leaves at least one byte and at most one block of input cached but unprocessed inside the ctx object. `CMAC_Update`() can be called multiple times to concatenate several chunks of input data of varying sizes.

`CMAC_Final`() stores the length of the message authentication code in bytes, which equals the cipher block size, into *out_len. Unless out_mac is `NULL`, it encrypts the last block, padding it if required, and copies the resulting message authentication code to out_mac. The caller is responsible for providing a buffer of sufficient size.

`CMAC_CTX_copy`() performs a deep copy of the already initialized in_ctx into out_ctx.

`CMAC_CTX_cleanup`() zeros out both subkeys and all temporary data in ctx and in the embedded EVP_CIPHER_CTX object, frees all allocated memory associated with it, except for ctx itself, and marks it as uninitialized, such that it can be reused for subsequent `CMAC_Init`().

`CMAC_CTX_free`() calls `CMAC_CTX_cleanup`(), then frees ctx itself. If ctx is `NULL`, no action occurs.

# RETURN VALUES

`CMAC_CTX_new`() returns the new context object or `NULL` in case of failure. It succeeds unless memory is exhausted.

`CMAC_Init`(), `CMAC_Update`(), `CMAC_Final`(), and `CMAC_CTX_copy`() return 1 on success or 0 on failure. `CMAC_Init`() fails if initializing the embedded EVP_CIPHER_CTX object fails. The others fail if in_ctx is uninitialized. `CMAC_Update`() and `CMAC_Final`() also fail if encrypting a block fails, and `CMAC_CTX_copy`() if copying the embedded EVP_CIPHER_CTX object fails, which can for example happen when memory is exhausted.

`CMAC_CTX_get0_cipher_ctx`() returns an internal pointer to the EVP_CIPHER_CTX object that is embedded in ctx.

# ERRORS

The CMAC code itself does not use the `<openssl/err.h>` framework, so in general, the reasons for failure cannot be found out with ERR_get_error(3). However, since the EVP_EncryptInit(3) functions are used internally, entries may still get pushed onto the error stack in some cases of failure.

# SEE ALSO

EVP_aes_128_cbc(3), EVP_DigestSignInit(3), EVP_EncryptInit(3), EVP_PKEY_new_CMAC_key(3), HMAC(3)

# STANDARDS

Morris Dworkin, Recommendation for Block Cipher Modes of Operation: The CMAC Mode for Authentication, National Institute of Standards and Technology, NIST Special Publication 800-38B, https://doi.org/10.6028/NIST.SP.800-38B, Gaithersburg, Maryland, May 2005, updated October 6, 2016.

# HISTORY

These functions first appeared in OpenSSL 1.0.1 and have been available since OpenBSD 5.3.

June 8, 2025 | Debian