1.\" $OpenBSD: CMAC_Init.3,v 1.4 2020/08/06 22:17:49 schwarze Exp $ 2.\" 3.\" Copyright (c) 2020 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: August 6 2020 $ 18.Dt CMAC_INIT 3 19.Os 20.Sh NAME 21.Nm CMAC_CTX_new , 22.Nm CMAC_Init , 23.Nm CMAC_Update , 24.Nm CMAC_Final , 25.Nm CMAC_resume , 26.Nm CMAC_CTX_copy , 27.Nm CMAC_CTX_get0_cipher_ctx , 28.Nm CMAC_CTX_cleanup , 29.Nm CMAC_CTX_free 30.Nd Cipher-based message authentication code 31.Sh SYNOPSIS 32.In openssl/cmac.h 33.Ft CMAC_CTX * 34.Fn CMAC_CTX_new void 35.Ft int 36.Fo CMAC_Init 37.Fa "CMAC_CTX *ctx" 38.Fa "const void *key" 39.Fa "size_t key_len" 40.Fa "const EVP_CIPHER *cipher" 41.Fa "ENGINE *impl" 42.Fc 43.Ft int 44.Fo CMAC_Update 45.Fa "CMAC_CTX *ctx" 46.Fa "const void *in_data" 47.Fa "size_t in_len" 48.Fc 49.Ft int 50.Fo CMAC_Final 51.Fa "CMAC_CTX *ctx" 52.Fa "unsigned char *out_mac" 53.Fa "size_t *out_len" 54.Fc 55.Ft int 56.Fn CMAC_resume "CMAC_CTX *ctx" 57.Ft int 58.Fo CMAC_CTX_copy 59.Fa "CMAC_CTX *out_ctx" 60.Fa "CMAC_CTX *in_ctx" 61.Fc 62.Ft EVP_CIPHER_CTX * 63.Fn CMAC_CTX_get0_cipher_ctx "CMAC_CTX *ctx" 64.Ft void 65.Fn CMAC_CTX_cleanup "CMAC_CTX *ctx" 66.Ft void 67.Fn CMAC_CTX_free "CMAC_CTX *ctx" 68.Sh DESCRIPTION 69CMAC is a message authentication code algorithm that can employ an 70arbitrary block cipher using a symmetric key. 71.Pp 72The present manual page describes low-level functions implementing CMAC. 73Instead of using these functions directly, 74application programs normally call 75.Xr EVP_PKEY_CTX_new_id 3 76with an argument of 77.Dv EVP_PKEY_CMAC 78and then pass the resulting 79.Vt EVP_MD_CTX 80object to 81.Xr EVP_DigestInit_ex 3 . 82.Pp 83The CMAC API is object-oriented. 84Calculating a message authentication code requires a 85.Vt CMAC_CTX 86object. 87Usually, the functions 88.Fn CMAC_CTX_new , 89.Fn CMAC_Init , 90.Fn CMAC_Update , 91.Fn CMAC_Final , 92and 93.Fn CMAC_CTX_free 94need to be called in this order. 95.Pp 96.Fn CMAC_CTX_new 97allocates a new 98.Vt CMAC_CTX 99object, initializes the embedded 100.Vt EVP_CIPHER_CTX 101object, and marks the object itself as uninitialized. 102.Pp 103.Fn CMAC_Init 104selects the given block 105.Fa cipher 106for use by 107.Fa ctx . 108Functions to obtain suitable 109.Vt EVP_CIPHER 110objects are listed in the CIPHER LISTING section of the 111.Xr EVP_Cipher 3 112manual page. 113Unless 114.Fa key 115is 116.Dv NULL , 117.Fn CMAC_Init 118also initializes 119.Fa ctx 120for use with the given symmetric 121.Fa key 122that is 123.Fa key_len 124bytes long. 125In particular, it calculates and internally stores the two subkeys 126and initializes 127.Fa ctx 128for subsequently feeding in data with 129.Fn CMAC_Update . 130To use the default cipher implementations provided by the library, pass 131.Dv NULL 132as the 133.Fa impl 134argument. 135.Pp 136If 137.Fa ctx 138is already initialized, 139.Fn CMAC_Init 140can be called again with 141.Fa key , 142.Fa cipher , 143and 144.Fa impl 145all set to 146.Dv NULL 147and 148.Fa key_len 149set to 0. 150In that case, any data already processed is discarded and 151.Fa ctx 152is re-initialized to start reading data anew. 153.Pp 154.Fn CMAC_Update 155processes 156.Fa in_len 157bytes of input data pointed to by 158.Fa in_data . 159Depending on the number of input bytes already cached in 160.Fa ctx , 161on 162.Fa in_len , 163and on the block size, this may encrypt zero or more blocks. 164Unless 165.Fa in_len 166is zero, this function leaves at least one byte and at most one 167block of input cached but unprocessed inside the 168.Fa ctx 169object. 170.Fn CMAC_Update 171can be called multiple times 172to concatenate several chunks of input data of varying sizes. 173.Pp 174.Fn CMAC_Final 175stores the length of the message authentication code in bytes, 176which equals the cipher block size, into 177.Pf * Fa out_len . 178Unless 179.Fa out_mac 180is 181.Dv NULL , 182it encrypts the last block, padding it if required, and copies the 183resulting message authentication code to 184.Fa out_mac . 185The caller is responsible for providing a buffer of sufficient size. 186.Pp 187Calling 188.Fn CMAC_resume 189after 190.Fn CMAC_Final 191allows the user to subsequently append additional data with 192.Fn CMAC_Update . 193Otherwise, unless 194.Fn CMAC_Init 195is called to start from scratch, 196.Fn CMAC_Update 197can no longer be used after 198.Fn CMAC_Final . 199.Pp 200.Fn CMAC_CTX_copy 201performs a deep copy of the already initialized 202.Fa in_ctx 203into 204.Fa out_ctx . 205.Pp 206.Fn CMAC_CTX_cleanup 207zeros out both subkeys and all temporary data in 208.Fa ctx 209and in the embedded 210.Vt EVP_CIPHER_CTX 211object, frees all allocated memory associated with it, 212except for 213.Fa ctx 214itself, and marks it as uninitialized, 215such that it can be reused for subsequent 216.Fn CMAC_Init . 217.Pp 218.Fn CMAC_CTX_free 219calls 220.Fn CMAC_CTX_cleanup , 221then frees 222.Fa ctx 223itself. 224If 225.Fa ctx 226is 227.Dv NULL , 228no action occurs. 229.Sh RETURN VALUES 230.Fn CMAC_CTX_new 231returns the new context object or 232.Dv NULL 233in case of failure. 234It succeeds unless memory is exhausted. 235.Pp 236.Fn CMAC_Init , 237.Fn CMAC_Update , 238.Fn CMAC_Final , 239.Fn CMAC_resume , 240and 241.Fn CMAC_CTX_copy 242return 1 on success or 0 on failure. 243.Fn CMAC_Init 244fails if initializing the embedded 245.Vt EVP_CIPHER_CTX 246object fails. 247The others fail if 248.Fa in_ctx 249is uninitialized. 250.Fn CMAC_Update 251and 252.Fn CMAC_Final 253also fail if encrypting a block fails, and 254.Fn CMAC_CTX_copy 255if copying the embedded 256.Vt EVP_CIPHER_CTX 257object fails, which can for example happen when memory is exhausted. 258.Pp 259.Fn CMAC_CTX_get0_cipher_ctx 260returns an internal pointer to the 261.Vt EVP_CIPHER_CTX 262object that is embedded in 263.Fa ctx . 264.Sh ERRORS 265The CMAC code itself does not use the 266.In openssl/err.h 267framework, so in general, the reasons for failure cannot be found out with 268.Xr ERR_get_error 3 . 269However, since the 270.Xr EVP_Cipher 3 271functions are used internally, entries may still get pushed onto 272the error stack in some cases of failure. 273.Sh SEE ALSO 274.Xr EVP_aes_128_cbc 3 , 275.Xr EVP_Cipher 3 , 276.Xr EVP_DigestInit 3 , 277.Xr EVP_PKEY_CTX_new_id 3 , 278.Xr HMAC 3 279.Sh STANDARDS 280.Rs 281.%A Morris Dworkin 282.%T "Recommendation for Block Cipher Modes of Operation:\ 283 The CMAC Mode for Authentication" 284.%I National Institute of Standards and Technology 285.%R NIST Special Publication 800-38B 286.%U https://doi.org/10.6028/NIST.SP.800-38B 287.%C Gaithersburg, Maryland 288.%D May 2005, updated October 6, 2016 289.Re 290.Sh HISTORY 291These functions first appeared in OpenSSL 1.0.1 292and have been available since 293.Ox 5.3 . 294