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
     #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);

     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_CTX_new_id(3) with an argument of EVP_PKEY_CMAC and then
     pass the resulting EVP_MD_CTX object to EVP_DigestInit_ex(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_Cipher(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_Cipher(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_Cipher(3), EVP_DigestInit(3),
     EVP_PKEY_CTX_new_id(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.

Linux 6.8.2-arch2-1              March 2, 2024             Linux 6.8.2-arch2-1