Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CMAC_INIT(3)		 BSD 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

     #include <openssl/cmac.h>

     CMAC_CTX *

     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_resume(CMAC_CTX *ctx);

     CMAC_CTX_copy(CMAC_CTX *out_ctx, CMAC_CTX *in_ctx);

     CMAC_CTX_get0_cipher_ctx(CMAC_CTX *ctx);

     CMAC_CTX_cleanup(CMAC_CTX *ctx);

     CMAC_CTX_free(CMAC_CTX *ctx);

     CMAC is a message authentication code algorithm that can employ an	arbi-
     trary 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 sec-
     tion 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 re-
     sponsible 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 af-
     ter 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 as-
     sociated 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 em-
     bedded 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),
     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,, 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.

BSD				August 6, 2020				   BSD


Want to link to this manual page? Use this URL:

home | help