Debian Codegraph @

upstream/debian-unstable/man3/HMAC.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "HMAC 3SSL"
58 .TH HMAC 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 HMAC,
65 HMAC_CTX_new,
66 HMAC_CTX_reset,
67 HMAC_CTX_free,
68 HMAC_Init,
69 HMAC_Init_ex,
70 HMAC_Update,
71 HMAC_Final,
72 HMAC_CTX_copy,
73 HMAC_CTX_set_flags,
74 HMAC_CTX_get_md,
75 HMAC_size
76 \&\- HMAC message authentication code
77 .SH SYNOPSIS
78 .IX Header "SYNOPSIS"
79 .Vb 1
80 \& #include <openssl/hmac.h>
81 \&
82 \& unsigned char *HMAC(const EVP_MD *evp_md, const void *key, int key_len,
83 \& const unsigned char *data, size_t data_len,
84 \& unsigned char *md, unsigned int *md_len);
85 .Ve
86 .PP
87 The following functions have been deprecated since OpenSSL 3.0, and can be
88 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
89 see \fBopenssl_user_macros\fR\|(7):
90 .PP
91 .Vb 2
92 \& HMAC_CTX *HMAC_CTX_new(void);
93 \& int HMAC_CTX_reset(HMAC_CTX *ctx);
94 \&
95 \& int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len,
96 \& const EVP_MD *md, ENGINE *impl);
97 \& int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, size_t len);
98 \& int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len);
99 \&
100 \& void HMAC_CTX_free(HMAC_CTX *ctx);
101 \&
102 \& int HMAC_CTX_copy(HMAC_CTX *dctx, HMAC_CTX *sctx);
103 \& void HMAC_CTX_set_flags(HMAC_CTX *ctx, unsigned long flags);
104 \& const EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx);
105 \&
106 \& size_t HMAC_size(const HMAC_CTX *e);
107 .Ve
108 .PP
109 The following function has been deprecated since OpenSSL 1.1.0, and can be
110 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
111 see \fBopenssl_user_macros\fR\|(7):
112 .PP
113 .Vb 2
114 \& int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,
115 \& const EVP_MD *md);
116 .Ve
117 .SH DESCRIPTION
118 .IX Header "DESCRIPTION"
119 HMAC is a MAC (message authentication code), i.e. a keyed hash
120 function used for message authentication, which is based on a hash
121 function.
122 .PP
123 \&\fBHMAC()\fR computes the message authentication code of the \fIdata_len\fR bytes at
124 \&\fIdata\fR using the hash function \fIevp_md\fR and the key \fIkey\fR which is
125 \&\fIkey_len\fR bytes long. The \fIkey\fR may also be NULL with \fIkey_len\fR being 0.
126 .PP
127 It places the result in \fImd\fR (which must have space for the output of
128 the hash function, which is no more than \fBEVP_MAX_MD_SIZE\fR bytes).
129 If \fImd\fR is NULL, the digest is placed in a static array. The size of
130 the output is placed in \fImd_len\fR, unless it is NULL. Note: passing a NULL
131 value for \fImd\fR to use the static array is not thread safe.
132 .PP
133 \&\fIevp_md\fR is a message digest such as \fBEVP_sha1()\fR, \fBEVP_ripemd160()\fR etc.
134 HMAC does not support variable output length digests such as \fBEVP_shake128()\fR and
135 \&\fBEVP_shake256()\fR.
136 .PP
137 \&\fBHMAC()\fR uses the default \fBOSSL_LIB_CTX\fR.
138 Use \fBEVP_Q_mac\fR\|(3) instead if a library context is required.
139 .PP
140 All of the functions described below are deprecated.
141 Applications should instead use \fBEVP_MAC_CTX_new\fR\|(3), \fBEVP_MAC_CTX_free\fR\|(3),
142 \&\fBEVP_MAC_init\fR\|(3), \fBEVP_MAC_update\fR\|(3) and \fBEVP_MAC_final\fR\|(3)
143 or the 'quick' single-shot MAC function \fBEVP_Q_mac\fR\|(3).
144 .PP
145 \&\fBHMAC_CTX_new()\fR creates a new HMAC_CTX in heap memory.
146 .PP
147 \&\fBHMAC_CTX_reset()\fR clears an existing \fBHMAC_CTX\fR and associated
148 resources, making it suitable for new computations as if it was newly
149 created with \fBHMAC_CTX_new()\fR.
150 .PP
151 \&\fBHMAC_CTX_free()\fR erases the key and other data from the \fBHMAC_CTX\fR,
152 releases any associated resources and finally frees the \fBHMAC_CTX\fR
153 itself. If the argument is NULL, nothing is done.
154 .PP
155 The following functions may be used if the message is not completely
156 stored in memory:
157 .PP
158 \&\fBHMAC_Init_ex()\fR initializes or reuses a \fBHMAC_CTX\fR structure to use the hash
159 function \fIevp_md\fR and key \fIkey\fR. If both are NULL, or if \fIkey\fR is NULL
160 and \fIevp_md\fR is the same as the previous call, then the
161 existing key is
162 reused. \fIctx\fR must have been created with \fBHMAC_CTX_new()\fR before the first use
163 of an \fBHMAC_CTX\fR in this function.
164 .PP
165 If \fBHMAC_Init_ex()\fR is called with \fIkey\fR NULL and \fIevp_md\fR is not the
166 same as the previous digest used by \fIctx\fR then an error is returned
167 because reuse of an existing key with a different digest is not supported.
168 .PP
169 \&\fBHMAC_Init()\fR initializes a \fBHMAC_CTX\fR structure to use the hash
170 function \fIevp_md\fR and the key \fIkey\fR which is \fIkey_len\fR bytes
171 long.
172 .PP
173 \&\fBHMAC_Update()\fR can be called repeatedly with chunks of the message to
174 be authenticated (\fIlen\fR bytes at \fIdata\fR).
175 .PP
176 \&\fBHMAC_Final()\fR places the message authentication code in \fImd\fR, which
177 must have space for the hash function output.
178 .PP
179 \&\fBHMAC_CTX_copy()\fR copies all of the internal state from \fIsctx\fR into \fIdctx\fR.
180 .PP
181 \&\fBHMAC_CTX_set_flags()\fR applies the specified flags to the internal EVP_MD_CTXs.
182 These flags have the same meaning as for \fBEVP_MD_CTX_set_flags\fR\|(3).
183 .PP
184 \&\fBHMAC_CTX_get_md()\fR returns the EVP_MD that has previously been set for the
185 supplied HMAC_CTX.
186 .PP
187 \&\fBHMAC_size()\fR returns the length in bytes of the underlying hash function output.
188 .SH "RETURN VALUES"
189 .IX Header "RETURN VALUES"
190 \&\fBHMAC()\fR returns a pointer to the message authentication code or NULL if
191 an error occurred.
192 .PP
193 \&\fBHMAC_CTX_new()\fR returns a pointer to a new \fBHMAC_CTX\fR on success or
194 NULL if an error occurred.
195 .PP
196 \&\fBHMAC_CTX_reset()\fR, \fBHMAC_Init_ex()\fR, \fBHMAC_Update()\fR, \fBHMAC_Final()\fR and
197 \&\fBHMAC_CTX_copy()\fR return 1 for success or 0 if an error occurred.
198 .PP
199 \&\fBHMAC_CTX_get_md()\fR return the EVP_MD previously set for the supplied HMAC_CTX or
200 NULL if no EVP_MD has been set.
201 .PP
202 \&\fBHMAC_size()\fR returns the length in bytes of the underlying hash function output
203 or zero on error.
204 .SH "CONFORMING TO"
205 .IX Header "CONFORMING TO"
206 RFC 2104
207 .SH "SEE ALSO"
208 .IX Header "SEE ALSO"
209 \&\fBSHA1\fR\|(3), \fBEVP_Q_mac\fR\|(3), \fBevp\fR\|(7)
210 .SH HISTORY
211 .IX Header "HISTORY"
212 All functions except for \fBHMAC()\fR were deprecated in OpenSSL 3.0.
213 .PP
214 \&\fBHMAC_CTX_init()\fR was replaced with \fBHMAC_CTX_reset()\fR in OpenSSL 1.1.0.
215 .PP
216 \&\fBHMAC_CTX_cleanup()\fR existed in OpenSSL before version 1.1.0.
217 .PP
218 \&\fBHMAC_CTX_new()\fR, \fBHMAC_CTX_free()\fR and \fBHMAC_CTX_get_md()\fR are new in OpenSSL 1.1.0.
219 .PP
220 \&\fBHMAC_Init_ex()\fR, \fBHMAC_Update()\fR and \fBHMAC_Final()\fR did not return values in
221 OpenSSL before version 1.0.0.
222 .SH COPYRIGHT
223 .IX Header "COPYRIGHT"
224 Copyright 2000\-2024 The OpenSSL Project Authors. All Rights Reserved.
225 .PP
226 Licensed under the Apache License 2.0 (the "License"). You may not use
227 this file except in compliance with the License. You can obtain a copy
228 in the file LICENSE in the source distribution or at
229 <https://www.openssl.org/source/license.html>.