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)|
Cipher-based message authentication code
#include <openssl/cmac.h>CMAC_CTX *
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); EVP_PKEY_CTX_new_id(3) with an argument of
EVP_PKEY_CMACand 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_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
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
NULLas the impl argument. If ctx is already initialized,
CMAC_Init() can be called again with key, cipher, and impl all set to
NULLand 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_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_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_CTX_cleanup(), then frees ctx itself. If ctx is
NULL, no action occurs.
CMAC_CTX_new() returns the new context object or
NULLin case of failure. It succeeds unless memory is exhausted.
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_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.
<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), EVP_PKEY_CTX_new_id(3), HMAC(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. OpenBSD 5.3.
|August 6, 2020||Debian|