Sortix nightly manual
This manual documents Sortix nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
CMAC_INIT(3) | Library Functions Manual | CMAC_INIT(3) |
NAME
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
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 *impl);
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_resume
(CMAC_CTX
*ctx);
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_CTX_new_id(3) with an argument ofEVP_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 after CMAC_Final
().
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
(),
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.
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.August 6, 2020 | Debian |