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