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

FreeBSD Manual Pages

  
 
  

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

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 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.

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.

FreeBSD	13.0			August 6, 2020			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CMAC_CTX_new&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help