xref: /openbsd-src/lib/libcrypto/man/HMAC.3 (revision 5a38ef86d0b61900239c7913d24a05e7b88a58f0) 
1.\" $OpenBSD: HMAC.3,v 1.17 2020/06/24 16:06:27 schwarze Exp $
2.\" full merge up to: OpenSSL crypto/hmac a528d4f0 Oct 27 13:40:11 2015 -0400
3.\" selective merge up to: OpenSSL man3/HMAC b3696a55 Sep 2 09:35:50 2017 -0400
4.\"
5.\" This file was written by Ulf Moeller <ulf@openssl.org>,
6.\" Richard Levitte <levitte@openssl.org>, and
7.\" Matt Caswell <matt@openssl.org>.
8.\" Copyright (c) 2000-2002, 2006, 2008, 2009, 2013, 2015, 2016
9.\" The OpenSSL Project.  All rights reserved.
10.\"
11.\" Redistribution and use in source and binary forms, with or without
12.\" modification, are permitted provided that the following conditions
13.\" are met:
14.\"
15.\" 1. Redistributions of source code must retain the above copyright
16.\"    notice, this list of conditions and the following disclaimer.
17.\"
18.\" 2. Redistributions in binary form must reproduce the above copyright
19.\"    notice, this list of conditions and the following disclaimer in
20.\"    the documentation and/or other materials provided with the
21.\"    distribution.
22.\"
23.\" 3. All advertising materials mentioning features or use of this
24.\"    software must display the following acknowledgment:
25.\"    "This product includes software developed by the OpenSSL Project
26.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
27.\"
28.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
29.\"    endorse or promote products derived from this software without
30.\"    prior written permission. For written permission, please contact
31.\"    openssl-core@openssl.org.
32.\"
33.\" 5. Products derived from this software may not be called "OpenSSL"
34.\"    nor may "OpenSSL" appear in their names without prior written
35.\"    permission of the OpenSSL Project.
36.\"
37.\" 6. Redistributions of any form whatsoever must retain the following
38.\"    acknowledgment:
39.\"    "This product includes software developed by the OpenSSL Project
40.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
41.\"
42.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
43.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
44.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
45.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
46.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
47.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
48.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
49.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
50.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
51.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
52.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
53.\" OF THE POSSIBILITY OF SUCH DAMAGE.
54.\"
55.Dd $Mdocdate: June 24 2020 $
56.Dt HMAC 3
57.Os
58.Sh NAME
59.Nm HMAC ,
60.Nm HMAC_CTX_new ,
61.Nm HMAC_CTX_reset ,
62.Nm HMAC_CTX_free ,
63.Nm HMAC_CTX_init ,
64.Nm HMAC_CTX_cleanup ,
65.Nm HMAC_cleanup ,
66.Nm HMAC_Init_ex ,
67.Nm HMAC_Init ,
68.Nm HMAC_Update ,
69.Nm HMAC_Final ,
70.Nm HMAC_CTX_copy ,
71.Nm HMAC_CTX_set_flags ,
72.Nm HMAC_CTX_get_md ,
73.Nm HMAC_size
74.Nd HMAC message authentication code
75.Sh SYNOPSIS
76.In openssl/hmac.h
77.Ft unsigned char *
78.Fo HMAC
79.Fa "const EVP_MD *evp_md"
80.Fa "const void *key"
81.Fa "int key_len"
82.Fa "const unsigned char *d"
83.Fa "size_t n"
84.Fa "unsigned char *md"
85.Fa "unsigned int *md_len"
86.Fc
87.Ft HMAC_CTX *
88.Fn HMAC_CTX_new void
89.Ft int
90.Fo HMAC_CTX_reset
91.Fa "HMAC_CTX *ctx"
92.Fc
93.Ft void
94.Fo HMAC_CTX_free
95.Fa "HMAC_CTX *ctx"
96.Fc
97.Ft void
98.Fo HMAC_CTX_init
99.Fa "HMAC_CTX *ctx"
100.Fc
101.Ft void
102.Fo HMAC_CTX_cleanup
103.Fa "HMAC_CTX *ctx"
104.Fc
105.Ft void
106.Fo HMAC_cleanup
107.Fa "HMAC_CTX *ctx"
108.Fc
109.Ft int
110.Fo HMAC_Init_ex
111.Fa "HMAC_CTX *ctx"
112.Fa "const void *key"
113.Fa "int key_len"
114.Fa "const EVP_MD *md"
115.Fa "ENGINE *impl"
116.Fc
117.Ft int
118.Fo HMAC_Init
119.Fa "HMAC_CTX *ctx"
120.Fa "const void *key"
121.Fa "int key_len"
122.Fa "const EVP_MD *md"
123.Fc
124.Ft int
125.Fo HMAC_Update
126.Fa "HMAC_CTX *ctx"
127.Fa "const unsigned char *data"
128.Fa "size_t len"
129.Fc
130.Ft int
131.Fo HMAC_Final
132.Fa "HMAC_CTX *ctx"
133.Fa "unsigned char *md"
134.Fa "unsigned int *len"
135.Fc
136.Ft int
137.Fo HMAC_CTX_copy
138.Fa "HMAC_CTX *dctx"
139.Fa "HMAC_CTX *sctx"
140.Fc
141.Ft void
142.Fo HMAC_CTX_set_flags
143.Fa "HMAC_CTX *ctx"
144.Fa "unsigned long flags"
145.Fc
146.Ft const EVP_MD *
147.Fo HMAC_CTX_get_md
148.Fa "const HMAC_CTX *ctx"
149.Fc
150.Ft size_t
151.Fo HMAC_size
152.Fa "const HMAC_CTX *e"
153.Fc
154.Sh DESCRIPTION
155HMAC is a MAC (message authentication code), i.e. a keyed hash
156function used for message authentication, which is based on a hash
157function.
158.Pp
159.Fn HMAC
160computes the message authentication code of the
161.Fa n
162bytes at
163.Fa d
164using the hash function
165.Fa evp_md
166and the key
167.Fa key
168which is
169.Fa key_len
170bytes long.
171.Pp
172It places the result in
173.Fa md ,
174which must have space for the output of the hash function, which is no
175more than
176.Dv EVP_MAX_MD_SIZE
177bytes.
178If
179.Fa md
180is
181.Dv NULL ,
182the digest is placed in a static array, which is not thread safe.
183The size of the output is placed in
184.Fa md_len ,
185unless it is
186.Dv NULL .
187.Pp
188.Fa evp_md
189can be
190.Xr EVP_sha1 3 ,
191.Xr EVP_ripemd160 3 ,
192etc.
193.Pp
194.Fn HMAC_CTX_new
195allocates and initializes a new
196.Vt HMAC_CTX
197object.
198.Pp
199.Fn HMAC_CTX_reset
200zeroes and re-initializes
201.Fa ctx
202and associated resources, making it suitable for new computations
203as if it was deleted with
204.Fn HMAC_CTX_free
205and newly created with
206.Fn HMAC_CTX_new .
207.Pp
208.Fn HMAC_CTX_free
209erases the key and other data from
210.Fa ctx ,
211releases any associated resources, and finally frees
212.Fa ctx
213itself.
214.Pp
215.Fn HMAC_CTX_init
216is a deprecated function to initialize an empty
217.Vt HMAC_CTX
218object, similar to
219.Fn CTX_new
220but without the allocation.
221Calling it is required for static objects and objects on the stack
222before using them.
223.Pp
224.Fn HMAC_CTX_cleanup
225is a deprecated function to erase the key and other data from
226.Fa ctx
227and release any associated resources, similar to
228.Fn HMAC_CTX_free
229but without freeing
230.Fa ctx
231itself.
232Calling it is required for static objects and objects on the stack
233that were initialized with
234.Fn HMAC_CTX_init
235and are no longer needed.
236.Pp
237.Fn HMAC_cleanup
238is an alias for
239.Fn HMAC_CTX_cleanup
240included for backward compatibility with 0.9.6b.
241It is deprecated and implemented as a macro.
242.Pp
243The following functions may be used if the message is not completely
244stored in memory:
245.Pp
246.Fn HMAC_Init_ex
247sets up or reuses
248.Fa ctx
249to use the hash function
250.Fa evp_md
251and the key
252.Fa key .
253Either can be
254.Dv NULL ,
255in which case the existing one is reused.
256The
257.Fa ctx
258must have been created with
259.Fn HMAC_CTX_new
260or initialized with
261.Fn HMAC_CTX_init
262before the first use in this function.
263If
264.Fn HMAC_Init_ex
265is called with a
266.Dv NULL
267.Fa key
268but
269.Fa evp_md
270is neither
271.Dv NULL
272nor the same as the previous digest used by
273.Fa ctx ,
274then an error is returned because reuse of an existing key with a
275different digest is not supported.
276.Pp
277.Fn HMAC_Init
278is a deprecated wrapper around
279.Fn HMAC_Init_ex .
280If called with both
281.Fa key
282and
283.Fa md ,
284it calls
285.Fn HMAC_CTX_init
286first, which only makes sense for an empty, uninitialized
287.Fa ctx ,
288but not for one already initialized with
289.Fn HMAC_CTX_new
290or
291.Fn HMAC_CTX_init .
292If
293.Fa key
294or
295.Fa md
296is
297.Dv NULL ,
298it does not call
299.Fn HMAC_CTX_init ;
300so in this case,
301.Fa ctx
302already needs to be initialized with
303.Fn HMAC_CTX_new
304or
305.Fn HMAC_CTX_init .
306.Pp
307.Fn HMAC_Update
308can be called repeatedly with chunks of the message to be authenticated
309.Pq Fa len No bytes at Fa data .
310.Pp
311.Fn HMAC_Final
312places the message authentication code in
313.Fa md ,
314which must have space for the hash function output.
315.Pp
316.Fn HMAC_CTX_copy
317copies all of the internal state from
318.Fa sctx
319into
320.Fa dctx .
321.Pp
322.Fn HMAC_CTX_set_flags
323applies the specified flags to the internal
324.Vt EVP_MD_CTX
325objects.
326Possible flag values
327.Dv EVP_MD_CTX_FLAG_*
328are defined in
329.In openssl/evp.h .
330.Pp
331.Fn HMAC_size
332returns the length in bytes of the underlying hash function output.
333It is implemented as a macro.
334.Sh RETURN VALUES
335.Fn HMAC
336returns a pointer to the message authentication code or
337.Dv NULL
338if an error occurred.
339.Pp
340.Fn HMAC_CTX_new
341returns a pointer to the new
342.Vt HMAC_CTX
343object or
344.Dv NULL
345if an error occurred.
346.Pp
347.Fn HMAC_CTX_reset ,
348.Fn HMAC_Init_ex ,
349.Fn HMAC_Update ,
350.Fn HMAC_Final ,
351and
352.Fn HMAC_CTX_copy
353return 1 for success or 0 if an error occurred.
354.Pp
355.Fn HMAC_CTX_get_md
356returns the message digest that was previously set for
357.Fa ctx
358with
359.Fn HMAC_Init_ex ,
360or
361.Dv NULL
362if none was set.
363.Pp
364.Fn HMAC_size
365returns the length in bytes of the underlying hash function output
366or 0 on error.
367.Sh SEE ALSO
368.Xr CMAC_Init 3 ,
369.Xr EVP_DigestInit 3
370.Sh STANDARDS
371RFC 2104
372.Sh HISTORY
373.Fn HMAC ,
374.Fn HMAC_cleanup ,
375.Fn HMAC_Init ,
376.Fn HMAC_Update ,
377.Fn HMAC_Final ,
378and
379.Fn HMAC_size
380first appeared in SSLeay 0.9.0 and have been available since
381.Ox 2.4 .
382.Pp
383.Fn HMAC_CTX_init ,
384.Fn HMAC_CTX_cleanup ,
385and
386.Fn HMAC_Init_ex
387first appeared in OpenSSL 0.9.7 and have been available since
388.Ox 3.2 .
389.Pp
390.Fn HMAC_CTX_set_flags
391first appeared in OpenSSL 0.9.7f and have been available since
392.Ox 3.8 .
393.Pp
394.Fn HMAC_CTX_copy
395first appeared in OpenSSL 1.0.0 and has been available since
396.Ox 4.9 .
397.Pp
398.Fn HMAC_CTX_new ,
399.Fn HMAC_CTX_reset ,
400.Fn HMAC_CTX_free ,
401and
402.Fn HMAC_CTX_get_md
403first appeared in OpenSSL 1.1.0 and have been available since
404.Ox 6.3 .
405