DragonFly On-Line Manual Pages
CMAC_INIT(3) DragonFly Library Functions Manual CMAC_INIT(3)
CMAC_CTX_new, CMAC_Init, CMAC_Update, CMAC_Final, CMAC_resume,
CMAC_CTX_copy, CMAC_CTX_get0_cipher_ctx, CMAC_CTX_cleanup, CMAC_CTX_free
- Cipher-based message authentication code
CMAC_Init(CMAC_CTX *ctx, const void *key, size_t key_len,
const EVP_CIPHER *cipher, ENGINE *impl);
CMAC_Update(CMAC_CTX *ctx, const void *in_data, size_t in_len);
CMAC_Final(CMAC_CTX *ctx, unsigned char *out_mac, size_t *out_len);
CMAC_CTX_copy(CMAC_CTX *out_ctx, CMAC_CTX *in_ctx);
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(). To use the default cipher implementations
provided by the library, pass NULL as the impl argument.
If ctx is already initialized, CMAC_Init() can be called again with key,
cipher, and impl all 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.
Calling CMAC_resume() after CMAC_Final() allows the user to subsequently
append additional data with CMAC_Update(). Otherwise, unless CMAC_Init()
is called to start from scratch, CMAC_Update() can no longer be used
CMAC_CTX_copy() performs a deep copy of the already initialized in_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.
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(), CMAC_resume(), 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.
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.
EVP_aes_128_cbc(3), EVP_Cipher(3), EVP_DigestInit(3),
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.
These functions first appeared in OpenSSL 1.0.1 and have been available
since OpenBSD 5.3.
DragonFly 6.1-DEVELOPMENT August 6, 2020 DragonFly 6.1-DEVELOPMENT