Don't allow SHAKE128/SHAKE256 with HMAC
[openssl.git] / doc / man3 / EVP_MAC.pod
1 =pod
2
3 =head1 NAME
4
5 EVP_MAC, EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_new_id, EVP_MAC_CTX_free,
6 EVP_MAC_CTX_copy, EVP_MAC_CTX_mac, EVP_MAC_size, EVP_MAC_init, EVP_MAC_update,
7 EVP_MAC_final, EVP_MAC_ctrl, EVP_MAC_vctrl, EVP_MAC_ctrl_str,
8 EVP_MAC_str2ctrl, EVP_MAC_hex2ctrl, EVP_MAC_nid, EVP_MAC_name,
9 EVP_get_macbyname, EVP_get_macbynid, EVP_get_macbyobj - EVP MAC routines
10
11 =head1 SYNOPSIS
12
13  #include <openssl/evp.h>
14
15  typedef struct evp_mac_st EVP_MAC;
16  typedef struct evp_mac_ctx_st EVP_MAC_CTX;
17
18  EVP_MAC_CTX *EVP_MAC_CTX_new(const EVP_MAC *mac);
19  EVP_MAC_CTX *EVP_MAC_CTX_new_id(int nid);
20  void EVP_MAC_CTX_free(EVP_MAC_CTX *ctx);
21  int EVP_MAC_CTX_copy(EVP_MAC_CTX *dest, EVP_MAC_CTX *src);
22  const EVP_MAC *EVP_MAC_CTX_mac(EVP_MAC_CTX *ctx);
23  size_t EVP_MAC_size(EVP_MAC_CTX *ctx);
24  int EVP_MAC_init(EVP_MAC_CTX *ctx);
25  int EVP_MAC_update(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
26  int EVP_MAC_final(EVP_MAC_CTX *ctx, unsigned char *out, size_t *poutlen);
27  int EVP_MAC_ctrl(EVP_MAC_CTX *ctx, int cmd, ...);
28  int EVP_MAC_vctrl(EVP_MAC_CTX *ctx, int cmd, va_list args);
29  int EVP_MAC_ctrl_str(EVP_MAC_CTX *ctx, const char *type, const char *value);
30  int EVP_MAC_str2ctrl(EVP_MAC_CTX *ctx, int cmd, const char *value);
31  int EVP_MAC_hex2ctrl(EVP_MAC_CTX *ctx, int cmd, const char *value);
32  int EVP_MAC_nid(const EVP_MAC *mac);
33  const char *EVP_MAC_name(const EVP_MAC *mac);
34  const EVP_MAC *EVP_get_macbyname(const char *name);
35  const EVP_MAC *EVP_get_macbynid(int nid);
36  const EVP_MAC *EVP_get_macbyobj(const ASN1_OBJECT *o);
37
38 =head1 DESCRIPTION
39
40 These types and functions help the application to calculate MACs of
41 different types and with different underlying algorithms if there are
42 any.
43
44 MACs are a bit complex insofar that some of them use other algorithms
45 for actual computation.  HMAC uses a digest, and CMAC uses a cipher.
46 Therefore, there are sometimes two contexts to keep track of, one for
47 the MAC algorithm itself and one for the underlying computation
48 algorithm if there is one.
49
50 To make things less ambiguous, this manual talks about a "context" or
51 "MAC context", which is to denote the MAC level context, and about a
52 "underlying context", or "computation context", which is to denote the
53 context for the underlying computation algorithm if there is one.
54
55 =head2 Types
56
57 B<EVP_MAC> is a type that holds the implementation of a MAC.
58
59 B<EVP_MAC_CTX> is a context type that holds internal MAC information
60 as well as a reference to a computation context, for those MACs that
61 rely on an underlying computation algorithm.
62
63 =head2 Context manipulation functions
64
65 EVP_MAC_CTX_new() creates a new context for the MAC type C<mac>.
66 EVP_MAC_CTX_new_id() creates a new context for the numerical MAC
67 identity <nid>.
68 The created context can then be used with most other functions
69 described here.
70
71 EVP_MAC_CTX_free() frees the contents of the context, including an
72 underlying context if there is one, as well as the context itself.
73 B<NULL> is a valid parameter, for which this function is a no-op.
74
75 EVP_MAC_CTX_copy() makes a deep copy of the C<src> context to the
76 C<dest> context.
77 The C<dest> context I<must> have been created before calling this
78 function.
79
80 EVP_MAC_CTX_mac() returns the B<EVP_MAC> associated with the context
81 C<ctx>.
82
83 =head2 Computing functions
84
85 EVP_MAC_init() sets up the underlying context with information given
86 through diverse controls.
87 This should be called before calling EVP_MAC_update() and
88 EVP_MAC_final().
89
90 EVP_MAC_update() adds C<datalen> bytes from C<data> to the MAC input.
91
92 EVP_MAC_final() does the final computation and stores the result in
93 the memory pointed at by C<out>, and sets its size in the B<size_t>
94 the C<poutlen> points at.
95 If C<out> is B<NULL>, then no computation is made.
96 To figure out what the output length will be and allocate space for it
97 dynamically, simply call with C<out> being B<NULL> and C<poutlen>
98 pointing at a valid location, then allocate space and make a second
99 call with C<out> pointing at the allocated space.
100
101 EVP_MAC_ctrl() is used to manipulate or get information on aspects of
102 the MAC which may vary depending on the MAC algorithm or its
103 implementation.
104 This includes the MAC key, and for MACs that use other algorithms to
105 do their computation, this is also the way to tell it which one to
106 use.
107 This functions takes variable arguments, the exact expected arguments
108 depend on C<cmd>.
109 EVP_MAC_ctrl() can be called both before and after EVP_MAC_init(), but
110 the effect will depend on what control is being use.
111 See L</CONTROLS> below for a description of standard controls.
112
113 EVP_MAC_vctrl() is the variant of EVP_MAC_ctrl() that takes a
114 C<va_list> argument instead of variadic arguments.
115
116 EVP_MAC_ctrl_str() is an alternative to EVP_MAC_ctrl() to control the
117 MAC implementation as E<lt> C<type>, C<value> E<gt> pairs.
118 The MAC implementation documentation should specify what control type
119 strings are accepted.
120
121 EVP_MAC_str2ctrl() and EVP_MAC_hex2ctrl() are helper functions to
122 control the MAC implementation with raw strings or with strings
123 containing hexadecimal numbers.
124 The latter are decoded into bitstrings that are sent on to
125 EVP_MAC_ctrl().
126
127 =head2 Information functions
128
129 EVP_MAC_size() returns the MAC output size for the given context.
130
131 EVP_MAC_nid() returns the numeric identity of the given MAC implementation.
132
133 EVP_MAC_name() returns the name of the given MAC implementation.
134
135 =head2 Object database functions
136
137 EVP_get_macbyname() fetches a MAC implementation from the object
138 database by name.
139
140 EVP_get_macbynid() fetches a MAC implementation from the object
141 database by numeric identity.
142
143 EVP_get_macbyobj() fetches a MAC implementation from the object
144 database by ASN.1 OBJECT (i.e. an encoded OID).
145
146 =head1 CONTROLS
147
148 The standard controls are:
149
150 =over 4
151
152 =item B<EVP_MAC_CTRL_SET_KEY>
153
154 This control expects two arguments: C<unsigned char *key>, C<size_t keylen>
155
156 These will set the MAC key from the given string of the given length.
157 The string may be any bitstring, and can contain NUL bytes.
158
159 For MACs that use an underlying computation algorithm, the algorithm
160 I<must> be set first, see B<EVP_MAC_CTRL_SET_ENGINE>,
161 B<EVP_MAC_CTRL_SET_MD> and B<EVP_MAC_CTRL_SET_CIPHER> below.
162
163 =item B<EVP_MAC_CTRL_SET_IV>
164
165 This control expects two arguments: C<unsigned char *key>, C<size_t keylen>
166
167 Some MAC implementations require an IV, this control sets the IV.
168
169 =item B<EVP_MAC_CTRL_SET_CUSTOM>
170
171 This control expects two arguments: C<unsigned char *custom>, C<size_t customlen>
172
173 Some MAC implementations (KMAC, BLAKE2) accept a Customization String,
174 this control sets the Customization String. The default value is "".
175
176 =item B<EVP_MAC_CTRL_SET_SALT>
177
178 This control expects two arguments: C<unsigned char *salt>, C<size_t saltlen>
179
180 This option is used by BLAKE2 MAC.
181
182 =item B<EVP_MAC_CTRL_SET_XOF>
183
184 This control expects one argument: C<int xof>
185
186 This option is used by KMAC.
187
188 =item B<EVP_MAC_CTRL_SET_FLAGS>
189
190 This control expects one argument: C<unsigned long flags>
191
192 These will set the MAC flags to the given numbers.
193 Some MACs do not support this option.
194
195 =item B<EVP_MAC_CTRL_SET_ENGINE>
196
197 =item B<EVP_MAC_CTRL_SET_MD>
198
199 =item B<EVP_MAC_CTRL_SET_CIPHER>
200
201 For MAC implementations that use an underlying computation algorithm,
202 these controls set what the algorithm should be, and the engine that
203 implements the algorithm if needed.
204
205 Note that not all algorithms may support all digests. HMAC does not support
206 variable output length digests such as SHAKE128 or SHAKE256.
207
208 B<EVP_MAC_CTRL_SET_ENGINE> takes one argument: C<ENGINE *>
209
210 B<EVP_MAC_CTRL_SET_MD> takes one argument: C<EVP_MD *>
211
212 B<EVP_MAC_CTRL_SET_CIPHER> takes one argument: C<EVP_CIPHER *>
213
214 =item B<EVP_MAC_CTRL_SET_SIZE>
215
216 For MAC implementations that support it, set the output size that
217 EVP_MAC_final() should produce.
218 The allowed sizes vary between MAC implementations.
219
220 =back
221
222 All these control should be used before the calls to any of
223 EVP_MAC_init(), EVP_MAC_update() and EVP_MAC_final() for a full
224 computation.
225 Anything else may give undefined results.
226
227 =head1 NOTES
228
229 EVP_get_macbynid(), EVP_get_macbyobj() and EVP_MAC_name() are
230 implemented as a macro.
231
232 =head1 RETURN VALUES
233
234 EVP_MAC_CTX_new() and EVP_MAC_CTX_new_id() return a pointer to a newly
235 created EVP_MAC_CTX, or NULL if allocation failed.
236
237 EVP_MAC_CTX_free() returns nothing at all.
238
239 EVP_MAC_CTX_copy(), EVP_MAC_init(), EVP_MAC_update(),
240 and EVP_MAC_final() return 1 on success, 0 on error.
241
242 EVP_MAC_ctrl(), EVP_MAC_ctrl_str(), EVP_MAC_str2ctrl() and
243 EVP_MAC_hex2ctrl() return 1 on success and 0 or a negative value on
244 error.
245 In particular, the value -2 indicates that the given control type
246 isn't supported by the MAC implementation.
247
248 EVP_MAC_size() returns the expected output size, or 0 if it isn't
249 set.
250 If it isn't set, a call to EVP_MAC_init() should get it set.
251
252 EVP_MAC_nid() returns the numeric identity for the given C<mac>.
253
254 EVP_MAC_name() returns the name for the given C<mac>, if it has been
255 added to the object database.
256
257 EVP_add_mac() returns 1 if the given C<mac> was successfully added to
258 the object database, otherwise 0.
259
260 EVP_get_macbyname(), EVP_get_macbynid() and EVP_get_macbyobj() return
261 the request MAC implementation, if it exists in the object database,
262 otherwise B<NULL>.
263
264 =head1 EXAMPLE
265
266   #include <stdlib.h>
267   #include <stdio.h>
268   #include <string.h>
269   #include <stdarg.h>
270   #include <unistd.h>
271
272   #include <openssl/evp.h>
273   #include <openssl/err.h>
274
275   int ctrl_ign_unsupported(EVP_MAC_CTX *ctx, int cmd, ...)
276   {
277       va_list args;
278       int rv;
279
280       va_start(args, cmd);
281       rv = EVP_MAC_vctrl(ctx, cmd, args);
282       va_end(args);
283
284       if (rv == -2)
285           rv = 1;       /* Ignore unsupported, pretend it worked fine */
286
287       return rv;
288   }
289
290   int main() {
291       const EVP_MAC *mac =
292           EVP_get_macbyname(getenv("MY_MAC"));
293       const EVP_CIPHER *cipher =
294           EVP_get_cipherbyname(getenv("MY_MAC_CIPHER"));
295       const EVP_MD *digest =
296           EVP_get_digestbyname(getenv("MY_MAC_DIGEST"));
297       const char *key = getenv("MY_KEY");
298       EVP_MAC_CTX *ctx = NULL;
299
300       unsigned char buf[4096];
301       ssize_t read_l;
302       size_t final_l;
303
304       size_t i;
305
306       if (mac == NULL
307           || key == NULL
308           || (ctx = EVP_MAC_CTX_new(mac)) == NULL
309           || (cipher != NULL
310               && !ctrl_ign_unsupported(ctx, EVP_MAC_CTRL_SET_CIPHER, cipher))
311           || (digest != NULL
312               && !ctrl_ign_unsupported(ctx, EVP_MAC_CTRL_SET_MD, digest))
313           || EVP_MAC_ctrl(ctx, EVP_MAC_CTRL_SET_KEY, key, strlen(key)) <= 0)
314           goto err;
315
316       if (!EVP_MAC_init(ctx))
317           goto err;
318
319       while ( (read_l = read(STDIN_FILENO, buf, sizeof(buf))) < 0) {
320           if (!EVP_MAC_update(ctx, buf, read_l))
321               goto err;
322       }
323
324       if (!EVP_MAC_final(ctx, buf, &final_l))
325           goto err;
326
327       printf("Result: ");
328       for (i = 0; i < final_l; i++)
329           printf("%02X", buf[i]);
330       printf("\n");
331
332       EVP_MAC_CTX_free(ctx);
333       exit(0);
334
335    err:
336       EVP_MAC_CTX_free(ctx);
337       fprintf(stderr, "Something went wrong\n");
338       ERR_print_errors_fp(stderr);
339       exit (1);
340   }
341
342 A run of this program, called with correct environment variables, can
343 look like this:
344
345   $ MY_MAC=cmac MY_KEY=secret0123456789 MY_MAC_CIPHER=aes-128-cbc \
346     LD_LIBRARY_PATH=. ./foo < foo.c
347   Result: ECCAAFF041B22A2299EB90A1B53B6D45
348
349 (in this example, that program was stored in F<foo.c> and compiled to
350 F<./foo>)
351
352 =head1 SEE ALSO
353
354 L<EVP_MAC_BLAKE2(7)>,
355 L<EVP_MAC_CMAC(7)>,
356 L<EVP_MAC_GMAC(7)>,
357 L<EVP_MAC_HMAC(7)>,
358 L<EVP_MAC_KMAC(7)>,
359 L<EVP_MAC_SIPHASH(7)>,
360 L<EVP_MAC_POLY1305(7)>
361
362 =head1 COPYRIGHT
363
364 Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
365
366 Licensed under the Apache License 2.0 (the "License").  You may not use
367 this file except in compliance with the License.  You can obtain a copy
368 in the file LICENSE in the source distribution or at
369 L<https://www.openssl.org/source/license.html>.
370
371 =cut