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