summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/HMAC.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/HMAC.3')
-rw-r--r--src/lib/libcrypto/man/HMAC.3324
1 files changed, 0 insertions, 324 deletions
diff --git a/src/lib/libcrypto/man/HMAC.3 b/src/lib/libcrypto/man/HMAC.3
deleted file mode 100644
index a515014fca..0000000000
--- a/src/lib/libcrypto/man/HMAC.3
+++ /dev/null
@@ -1,324 +0,0 @@
1.\" $OpenBSD: HMAC.3,v 1.23 2024/08/29 20:21:53 tb 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: August 29 2024 $
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_Init_ex ,
64.Nm HMAC_Update ,
65.Nm HMAC_Final ,
66.Nm HMAC_CTX_copy ,
67.Nm HMAC_CTX_set_flags ,
68.Nm HMAC_CTX_get_md ,
69.Nm HMAC_size
70.Nd HMAC message authentication code
71.Sh SYNOPSIS
72.In openssl/hmac.h
73.Ft unsigned char *
74.Fo HMAC
75.Fa "const EVP_MD *evp_md"
76.Fa "const void *key"
77.Fa "int key_len"
78.Fa "const unsigned char *d"
79.Fa "size_t n"
80.Fa "unsigned char *md"
81.Fa "unsigned int *md_len"
82.Fc
83.Ft HMAC_CTX *
84.Fn HMAC_CTX_new void
85.Ft int
86.Fo HMAC_CTX_reset
87.Fa "HMAC_CTX *ctx"
88.Fc
89.Ft void
90.Fo HMAC_CTX_free
91.Fa "HMAC_CTX *ctx"
92.Fc
93.Ft int
94.Fo HMAC_Init_ex
95.Fa "HMAC_CTX *ctx"
96.Fa "const void *key"
97.Fa "int key_len"
98.Fa "const EVP_MD *md"
99.Fa "ENGINE *engine"
100.Fc
101.Ft int
102.Fo HMAC_Update
103.Fa "HMAC_CTX *ctx"
104.Fa "const unsigned char *data"
105.Fa "size_t len"
106.Fc
107.Ft int
108.Fo HMAC_Final
109.Fa "HMAC_CTX *ctx"
110.Fa "unsigned char *md"
111.Fa "unsigned int *len"
112.Fc
113.Ft int
114.Fo HMAC_CTX_copy
115.Fa "HMAC_CTX *dctx"
116.Fa "HMAC_CTX *sctx"
117.Fc
118.Ft void
119.Fo HMAC_CTX_set_flags
120.Fa "HMAC_CTX *ctx"
121.Fa "unsigned long flags"
122.Fc
123.Ft const EVP_MD *
124.Fo HMAC_CTX_get_md
125.Fa "const HMAC_CTX *ctx"
126.Fc
127.Ft size_t
128.Fo HMAC_size
129.Fa "const HMAC_CTX *e"
130.Fc
131.Sh DESCRIPTION
132HMAC is a MAC (message authentication code), i.e. a keyed hash
133function used for message authentication, which is based on a hash
134function.
135.Pp
136.Fn HMAC
137computes the message authentication code of the
138.Fa n
139bytes at
140.Fa d
141using the hash function
142.Fa evp_md
143and the key
144.Fa key
145which is
146.Fa key_len
147bytes long.
148.Pp
149It places the result in
150.Fa md ,
151which must have space for the output of the hash function, which is no
152more than
153.Dv EVP_MAX_MD_SIZE
154bytes.
155The size of the output is placed in
156.Fa md_len ,
157unless it is
158.Dv NULL .
159.Pp
160.Fa evp_md
161can be
162.Xr EVP_sha1 3 ,
163.Xr EVP_ripemd160 3 ,
164etc.
165.Pp
166.Fn HMAC_CTX_new
167allocates and initializes a new
168.Vt HMAC_CTX
169object.
170.Pp
171.Fn HMAC_CTX_reset
172zeroes and re-initializes
173.Fa ctx
174and associated resources, making it suitable for new computations
175as if it was deleted with
176.Fn HMAC_CTX_free
177and newly created with
178.Fn HMAC_CTX_new .
179.Pp
180.Fn HMAC_CTX_free
181erases the key and other data from
182.Fa ctx ,
183releases any associated resources, and finally frees
184.Fa ctx
185itself.
186.Pp
187The following functions may be used if the message is not completely
188stored in memory:
189.Pp
190.Fn HMAC_Init_ex
191sets up or reuses
192.Fa ctx
193to use the hash function
194.Fa evp_md
195and the key
196.Fa key .
197Either can be
198.Dv NULL ,
199in which case the existing one is reused.
200The
201.Fa ctx
202must have been created with
203.Fn HMAC_CTX_new
204before the first use in this function.
205If
206.Fn HMAC_Init_ex
207is called with a
208.Dv NULL
209.Fa key
210but
211.Fa evp_md
212is neither
213.Dv NULL
214nor the same as the previous digest used by
215.Fa ctx ,
216then an error is returned because reuse of an existing key with a
217different digest is not supported.
218The
219.Fa ENGINE *engine
220argument is always ignored and passing
221.Dv NULL
222is recommended.
223.Pp
224.Fn HMAC_Update
225can be called repeatedly with chunks of the message to be authenticated
226.Pq Fa len No bytes at Fa data .
227.Pp
228.Fn HMAC_Final
229places the message authentication code in
230.Fa md ,
231which must have space for the hash function output.
232.Pp
233.Fn HMAC_CTX_copy
234copies all of the internal state from
235.Fa sctx
236into
237.Fa dctx .
238.Pp
239.Fn HMAC_CTX_set_flags
240applies the specified flags to the internal
241.Vt EVP_MD_CTX
242objects.
243Possible flag values
244.Dv EVP_MD_CTX_FLAG_*
245are defined in
246.In openssl/evp.h .
247.Pp
248.Fn HMAC_size
249returns the length in bytes of the underlying hash function output.
250It is implemented as a macro.
251.Sh RETURN VALUES
252.Fn HMAC
253returns a pointer to the message authentication code or
254.Dv NULL
255if an error occurred.
256.Pp
257.Fn HMAC_CTX_new
258returns a pointer to the new
259.Vt HMAC_CTX
260object or
261.Dv NULL
262if an error occurred.
263.Pp
264.Fn HMAC_CTX_reset ,
265.Fn HMAC_Init_ex ,
266.Fn HMAC_Update ,
267.Fn HMAC_Final ,
268and
269.Fn HMAC_CTX_copy
270return 1 for success or 0 if an error occurred.
271.Pp
272.Fn HMAC_CTX_get_md
273returns the message digest that was previously set for
274.Fa ctx
275with
276.Fn HMAC_Init_ex ,
277or
278.Dv NULL
279if none was set.
280.Pp
281.Fn HMAC_size
282returns the length in bytes of the underlying hash function output
283or 0 on error.
284.Sh SEE ALSO
285.Xr CMAC_Init 3 ,
286.Xr EVP_DigestInit 3
287.Sh STANDARDS
288RFC 2104
289.Sh HISTORY
290.Fn HMAC ,
291.Fn HMAC_Update ,
292.Fn HMAC_Final ,
293and
294.Fn HMAC_size
295first appeared in SSLeay 0.9.0 and have been available since
296.Ox 2.4 .
297.Pp
298.Fn HMAC_Init_ex
299first appeared in OpenSSL 0.9.7 and have been available since
300.Ox 3.2 .
301.Pp
302.Fn HMAC_CTX_set_flags
303first appeared in OpenSSL 0.9.7f and have been available since
304.Ox 3.8 .
305.Pp
306.Fn HMAC_CTX_copy
307first appeared in OpenSSL 1.0.0 and has been available since
308.Ox 4.9 .
309.Pp
310.Fn HMAC_CTX_new ,
311.Fn HMAC_CTX_reset ,
312.Fn HMAC_CTX_free ,
313and
314.Fn HMAC_CTX_get_md
315first appeared in OpenSSL 1.1.0 and have been available since
316.Ox 6.3 .
317.Sh CAVEATS
318Other implementations allow
319.Fa md
320in
321.Fn HMAC
322to be
323.Dv NULL
324and return a static array, which is not thread safe.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-12-23 15:18:05 +0000