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