1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
.\" $OpenBSD: HMAC.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
.\"
.Dd $Mdocdate: November 6 2016 $
.Dt HMAC 3
.Os
.Sh NAME
.Nm HMAC ,
.Nm HMAC_Init ,
.Nm HMAC_Update ,
.Nm HMAC_Final ,
.Nm HMAC_cleanup
.Nd HMAC message authentication code
.Sh SYNOPSIS
.In openssl/hmac.h
.Ft unsigned char *
.Fo HMAC
.Fa "const EVP_MD *evp_md"
.Fa "const void *key"
.Fa "int key_len"
.Fa "const unsigned char *d"
.Fa "int n"
.Fa "unsigned char *md"
.Fa "unsigned int *md_len"
.Fc
.Ft void
.Fo HMAC_CTX_init
.Fa "HMAC_CTX *ctx"
.Fc
.Ft int
.Fo HMAC_Init
.Fa "HMAC_CTX *ctx"
.Fa "const void *key"
.Fa "int key_len"
.Fa "const EVP_MD *md"
.Fc
.Ft int
.Fo HMAC_Init_ex
.Fa "HMAC_CTX *ctx"
.Fa "const void *key"
.Fa "int key_len"
.Fa "const EVP_MD *md"
.Fa "ENGINE *impl"
.Fc
.Ft int
.Fo HMAC_Update
.Fa "HMAC_CTX *ctx"
.Fa "const unsigned char *data"
.Fa "int len"
.Fc
.Ft int
.Fo HMAC_Final
.Fa "HMAC_CTX *ctx"
.Fa "unsigned char *md"
.Fa "unsigned int *len"
.Fc
.Ft void
.Fo HMAC_CTX_cleanup
.Fa "HMAC_CTX *ctx"
.Fc
.Ft void
.Fo HMAC_cleanup
.Fa "HMAC_CTX *ctx"
.Fc
.Sh DESCRIPTION
HMAC is a MAC (message authentication code), i.e. a keyed hash
function used for message authentication, which is based on a hash
function.
.Pp
.Fn HMAC
computes the message authentication code of the
.Fa n
bytes at
.Fa d
using the hash function
.Fa evp_md
and the key
.Fa key
which is
.Fa key_len
bytes long.
.Pp
It places the result in
.Fa md ,
which must have space for the output of the hash function, which is no
more than
.Dv EVP_MAX_MD_SIZE
bytes.
If
.Fa md
is
.Dv NULL ,
the digest is placed in a static array.
The size of the output is placed in
.Fa md_len ,
unless it is
.Dv NULL .
.Pp
.Fa evp_md
can be
.Xr EVP_sha1 3 ,
.Xr EVP_ripemd160 3 ,
etc.
.Pp
.Fn HMAC_CTX_init
initialises a
.Vt HMAC_CTX
before first use.
It must be called.
.Pp
.Fn HMAC_CTX_cleanup
erases the key and other data from the
.Vt HMAC_CTX
and releases any associated resources.
It must be called when an
.Vt HMAC_CTX
is no longer required.
.Pp
.Fn HMAC_cleanup
is an alias for
.Fn HMAC_CTX_cleanup
included for backward compatibility with 0.9.6b.
It is deprecated.
.Pp
The following functions may be used if the message is not completely
stored in memory:
.Pp
.Fn HMAC_Init
initializes a
.Vt HMAC_CTX
structure to use the hash function
.Fa evp_md
and the key
.Fa key
which is
.Fa key_len
bytes long.
It is deprecated and only included for backward compatibility with
OpenSSL 0.9.6b.
.Pp
.Fn HMAC_Init_ex
initializes or reuses a
.Vt HMAC_CTX
structure to use the function
.Fa evp_md
and key
.Fa key .
Either can be
.Dv NULL ,
in which case the existing one will be reused.
.Fn HMAC_CTX_init
must have been called before the first use of an
.Vt HMAC_CTX
in this function.
.Sy N.B.
.Fn HMAC_Init
had this undocumented behaviour in previous versions of OpenSSL -
failure to switch to
.Fn HMAC_Init_ex
in programs that expect it will cause them to stop working.
.Pp
.Fn HMAC_Update
can be called repeatedly with chunks of the message to be authenticated
.Pq Fa len No bytes at Fa data .
.Pp
.Fn HMAC_Final
places the message authentication code in
.Fa md ,
which must have space for the hash function output.
.Sh RETURN VALUES
.Fn HMAC
returns a pointer to the message authentication code or
.Dv NULL
if an error occurred.
.Pp
.Fn HMAC_Init_ex ,
.Fn HMAC_Update ,
and
.Fn HMAC_Final
return 1 for success or 0 if an error occurred.
.Pp
.Fn HMAC_CTX_init
and
.Fn HMAC_CTX_cleanup
do not return values.
.Sh SEE ALSO
.Xr evp 3
.Sh STANDARDS
RFC 2104
.Sh HISTORY
.Fn HMAC ,
.Fn HMAC_Init ,
.Fn HMAC_Update ,
.Fn HMAC_Final ,
and
.Fn HMAC_cleanup
are available since SSLeay 0.9.0.
.Pp
.Fn HMAC_CTX_init ,
.Fn HMAC_Init_ex ,
and
.Fn HMAC_CTX_cleanup
are available since OpenSSL 0.9.7.
.Pp
.Fn HMAC_Init_ex ,
.Fn HMAC_Update ,
and
.Fn HMAC_Final
did not return values in versions of OpenSSL before 1.0.0.
|
