EVP: add name traversal functions to all fetchable types
[openssl.git] / doc / man3 / EVP_MAC.pod
1 =pod
2
3 =head1 NAME
4
5 EVP_MAC, EVP_MAC_fetch, EVP_MAC_up_ref, EVP_MAC_free,
6 EVP_MAC_is_a, EVP_MAC_names_do_all,
7 EVP_MAC_provider, EVP_MAC_get_params, EVP_MAC_gettable_params,
8 EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_free, EVP_MAC_CTX_dup,
9 EVP_MAC_CTX_mac, EVP_MAC_CTX_get_params, EVP_MAC_CTX_set_params,
10 EVP_MAC_size, EVP_MAC_init, EVP_MAC_update, EVP_MAC_final,
11 EVP_MAC_gettable_ctx_params, EVP_MAC_settable_ctx_params,
12 EVP_MAC_do_all_provided - EVP MAC routines
13
14 =head1 SYNOPSIS
15
16  #include <openssl/evp.h>
17
18  typedef struct evp_mac_st EVP_MAC;
19  typedef struct evp_mac_ctx_st EVP_MAC_CTX;
20
21  EVP_MAC *EVP_MAC_fetch(OPENSSL_CTX *libctx, const char *algorithm,
22                         const char *properties);
23  int EVP_MAC_up_ref(EVP_MAC *mac);
24  void EVP_MAC_free(EVP_MAC *mac);
25  int EVP_MAC_is_a(const EVP_MAC *mac, const char *name);
26  void EVP_MAC_names_do_all(const EVP_MAC *mac,
27                            void (*fn)(const char *name, void *data),
28                            void *data);
29  const OSSL_PROVIDER *EVP_MAC_provider(const EVP_MAC *mac);
30  int EVP_MAC_get_params(EVP_MAC *mac, OSSL_PARAM params[]);
31
32  EVP_MAC_CTX *EVP_MAC_CTX_new(EVP_MAC *mac);
33  void EVP_MAC_CTX_free(EVP_MAC_CTX *ctx);
34  EVP_MAC_CTX *EVP_MAC_CTX_dup(const EVP_MAC_CTX *src);
35  EVP_MAC *EVP_MAC_CTX_mac(EVP_MAC_CTX *ctx);
36  int EVP_MAC_CTX_get_params(EVP_MAC_CTX *ctx, OSSL_PARAM params[]);
37  int EVP_MAC_CTX_set_params(EVP_MAC_CTX *ctx, const OSSL_PARAM params[]);
38
39  size_t EVP_MAC_size(EVP_MAC_CTX *ctx);
40  int EVP_MAC_init(EVP_MAC_CTX *ctx);
41  int EVP_MAC_update(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
42  int EVP_MAC_final(EVP_MAC_CTX *ctx,
43                    unsigned char *out, size_t *outl, size_t outsize);
44
45  const OSSL_PARAM *EVP_MAC_gettable_params(const EVP_MAC *mac);
46  const OSSL_PARAM *EVP_MAC_gettable_ctx_params(const EVP_MAC *mac);
47  const OSSL_PARAM *EVP_MAC_settable_ctx_params(const EVP_MAC *mac);
48
49  void EVP_MAC_do_all_provided(OPENSSL_CTX *libctx,
50                               void (*fn)(EVP_MAC *mac, void *arg),
51                               void *arg);
52
53 =head1 DESCRIPTION
54
55 These types and functions help the application to calculate MACs of
56 different types and with different underlying algorithms if there are
57 any.
58
59 MACs are a bit complex insofar that some of them use other algorithms
60 for actual computation.  HMAC uses a digest, and CMAC uses a cipher.
61 Therefore, there are sometimes two contexts to keep track of, one for
62 the MAC algorithm itself and one for the underlying computation
63 algorithm if there is one.
64
65 To make things less ambiguous, this manual talks about a "context" or
66 "MAC context", which is to denote the MAC level context, and about a
67 "underlying context", or "computation context", which is to denote the
68 context for the underlying computation algorithm if there is one.
69
70 =head2 Types
71
72 B<EVP_MAC> is a type that holds the implementation of a MAC.
73
74 B<EVP_MAC_CTX> is a context type that holds internal MAC information
75 as well as a reference to a computation context, for those MACs that
76 rely on an underlying computation algorithm.
77
78 =head2 Algorithm implementation fetching
79
80 EVP_MAC_fetch() fetches an implementation of a MAC I<algorithm>, given
81 a library context I<libctx> and a set of I<properties>.
82 See L<provider(7)/Fetching algorithms> for further information.
83
84 The returned value must eventually be freed with
85 L<EVP_MAC_free(3)>.
86
87 EVP_MAC_up_ref() increments the reference count of an already fetched
88 MAC.
89
90 EVP_MAC_free() frees a fetched algorithm.
91 NULL is a valid parameter, for which this function is a no-op.
92
93 =head2 Context manipulation functions
94
95 EVP_MAC_CTX_new() creates a new context for the MAC type I<mac>.
96 The created context can then be used with most other functions
97 described here.
98
99 EVP_MAC_CTX_free() frees the contents of the context, including an
100 underlying context if there is one, as well as the context itself.
101 NULL is a valid parameter, for which this function is a no-op.
102
103 EVP_MAC_CTX_dup() duplicates the I<src> context and returns a newly allocated
104 context.
105
106 EVP_MAC_CTX_mac() returns the B<EVP_MAC> associated with the context
107 I<ctx>.
108
109 =head2 Computing functions
110
111 EVP_MAC_init() sets up the underlying context with information given
112 through diverse controls.
113 This should be called before calling EVP_MAC_update() and
114 EVP_MAC_final().
115
116 EVP_MAC_update() adds I<datalen> bytes from I<data> to the MAC input.
117
118 EVP_MAC_final() does the final computation and stores the result in
119 the memory pointed at by I<out> of size I<outsize>, and sets the number
120 of bytes written in I<*outl> at.
121 If I<out> is NULL or I<outsize> is too small, then no computation
122 is made.
123 To figure out what the output length will be and allocate space for it
124 dynamically, simply call with I<out> being NULL and I<outl>
125 pointing at a valid location, then allocate space and make a second
126 call with I<out> pointing at the allocated space.
127
128 EVP_MAC_get_params() retrieves details about the implementation
129 I<mac>.
130 The set of parameters given with I<params> determine exactly what
131 parameters should be retrieved.
132 Note that a parameter that is unknown in the underlying context is
133 simply ignored.
134
135 EVP_MAC_CTX_get_params() retrieves chosen parameters, given the
136 context I<ctx> and its underlying context.
137 The set of parameters given with I<params> determine exactly what
138 parameters should be retrieved.
139 Note that a parameter that is unknown in the underlying context is
140 simply ignored.
141
142 EVP_MAC_CTX_set_params() passes chosen parameters to the underlying
143 context, given a context I<ctx>.
144 The set of parameters given with I<params> determine exactly what
145 parameters are passed down.
146 Note that a parameter that is unknown in the underlying context is
147 simply ignored.
148 Also, what happens when a needed parameter isn't passed down is
149 defined by the implementation.
150
151 EVP_MAC_gettable_params(), EVP_MAC_gettable_ctx_params() and
152 EVP_MAC_settable_ctx_params() get a constant B<OSSL_PARAM> array that
153 decribes the retrievable and settable parameters, i.e. parameters that
154 can be used with EVP_MAC_get_params(), EVP_MAC_CTX_get_params()
155 and EVP_MAC_CTX_set_params(), respectively.
156 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
157
158 =head2 Information functions
159
160 EVP_MAC_size() returns the MAC output size for the given context.
161
162 EVP_MAC_is_a() checks if the given I<mac> is an implementation of an
163 algorithm that's identifiable with I<name>.
164
165 EVP_MAC_provider() returns the provider that holds the implementation
166 of the given I<mac>.
167
168 EVP_MAC_do_all_provided() traverses all MAC implemented by all activated
169 providers in the given library context I<libctx>, and for each of the
170 implementations, calls the given function I<fn> with the implementation method
171 and the given I<arg> as argument.
172
173 EVP_MAC_names_do_all() traverses all names for I<mac>, and calls
174 I<fn> with each name and I<data>.
175
176 =head1 PARAMETERS
177
178 Parameters are identified by name as strings, and have an expected
179 data type and maximum size.
180 OpenSSL has a set of macros for parameter names it expects to see in
181 its own MAC implementations.
182 Here, we show all three, the OpenSSL macro for the parameter name, the
183 name in string form, and a type description.
184
185 The standard parameter names are:
186
187 =over 4
188
189 =item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string>
190
191 Its value is the MAC key as an array of bytes.
192
193 For MACs that use an underlying computation algorithm, the algorithm
194 must be set first, see parameter names "algorithm" below.
195
196 =item "iv" (B<OSSL_MAC_PARAM_IV>) <octet string>
197
198 Some MAC implementations require an IV, this parameter sets the IV.
199
200 =item "custom" (B<OSSL_MAC_PARAM_CUSTOM>) <octet string>
201
202 Some MAC implementations (KMAC, BLAKE2) accept a Customization String,
203 this parameter sets the Customization String. The default value is the
204 empty string.
205
206 =item "salt" (B<OSSL_MAC_PARAM_SALT>) <octet string>
207
208 This option is used by BLAKE2 MAC.
209
210 =item "xof" (B<OSSL_MAC_PARAM_XOF>) <integer>
211
212 It's a simple flag, the value 0 or 1 are expected.
213
214 This option is used by KMAC.
215
216 =item "flags" (B<OSSL_MAC_PARAM_FLAGS>) <integer>
217
218 These will set the MAC flags to the given numbers.
219 Some MACs do not support this option.
220
221 =item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string>
222
223 =item "digest" (B<OSSL_MAC_PARAM_DIGEST>) <UTF8 string>
224
225 =item "cipher" (B<OSSL_MAC_PARAM_CIPHER>) <UTF8 string>
226
227 For MAC implementations that use an underlying computation cipher or
228 digest, these parameters set what the algorithm should be.
229
230 The value is always the name of the intended algorithm,
231 or the properties.
232
233 Note that not all algorithms may support all digests.
234 HMAC does not support variable output length digests such as SHAKE128
235 or SHAKE256.
236
237 =item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
238
239 For MAC implementations that support it, set the output size that
240 EVP_MAC_final() should produce.
241 The allowed sizes vary between MAC implementations, but must never exceed
242 what can be given with a B<size_t>.
243
244 =back
245
246 All these parameters should be used before the calls to any of
247 EVP_MAC_init(), EVP_MAC_update() and EVP_MAC_final() for a full
248 computation.
249 Anything else may give undefined results.
250
251 =head1 RETURN VALUES
252
253 EVP_MAC_fetch() returns a pointer to a newly fetched EVP_MAC, or
254 NULL if allocation failed.
255
256 EVP_MAC_up_ref() returns 1 on success, 0 on error.
257
258 EVP_MAC_free() returns nothing at all.
259
260 EVP_MAC_is_a() returns 1 if the given method can be identified with
261 the given name, otherwise 0.
262
263 EVP_MAC_provider() returns a pointer to the provider for the MAC, or
264 NULL on error.
265
266 EVP_MAC_CTX_new() and EVP_MAC_CTX_dup() return a pointer to a newly
267 created EVP_MAC_CTX, or NULL if allocation failed.
268
269 EVP_MAC_CTX_free() returns nothing at all.
270
271 EVP_MAC_CTX_get_params() and EVP_MAC_CTX_set_params() return 1 on
272 success, 0 on error.
273
274 EVP_MAC_init(), EVP_MAC_update(), and EVP_MAC_final() return 1 on success, 0
275 on error.
276
277 EVP_MAC_size() returns the expected output size, or 0 if it isn't
278 set.
279 If it isn't set, a call to EVP_MAC_init() should get it set.
280
281 EVP_MAC_do_all_provided() returns nothing at all.
282
283 =head1 EXAMPLES
284
285   #include <stdlib.h>
286   #include <stdio.h>
287   #include <string.h>
288   #include <stdarg.h>
289   #include <unistd.h>
290
291   #include <openssl/evp.h>
292   #include <openssl/err.h>
293   #include <openssl/params.h>
294
295   int main() {
296       EVP_MAC *mac = EVP_MAC_fetch(NULL, getenv("MY_MAC"), NULL);
297       const char *cipher = getenv("MY_MAC_CIPHER");
298       const char *digest = getenv("MY_MAC_DIGEST");
299       const char *key = getenv("MY_KEY");
300       EVP_MAC_CTX *ctx = NULL;
301
302       unsigned char buf[4096];
303       ssize_t read_l;
304       size_t final_l;
305
306       size_t i;
307
308       OSSL_PARAM params[4];
309       size_t params_n = 0;
310
311       if (cipher != NULL)
312           params[params_n++] =
313               OSSL_PARAM_construct_utf8_string("cipher", cipher, 0, NULL);
314       if (digest != NULL)
315           params[params_n++] =
316               OSSL_PARAM_construct_utf8_string("digest", digest, 0, NULL);
317       params[params_n++] =
318           OSSL_PARAM_construct_octet_string("key", key, strlen(key), NULL);
319       params[params_n] = OSSL_PARAM_construct_end();
320
321       if (mac == NULL
322           || key == NULL
323           || (ctx = EVP_MAC_CTX_new(mac)) == NULL
324           || EVP_MAC_CTX_set_params(ctx, params) <= 0)
325           goto err;
326
327       if (!EVP_MAC_init(ctx))
328           goto err;
329
330       while ( (read_l = read(STDIN_FILENO, buf, sizeof(buf))) < 0) {
331           if (!EVP_MAC_update(ctx, buf, read_l))
332               goto err;
333       }
334
335       if (!EVP_MAC_final(ctx, buf, &final_l))
336           goto err;
337
338       printf("Result: ");
339       for (i = 0; i < final_l; i++)
340           printf("%02X", buf[i]);
341       printf("\n");
342
343       EVP_MAC_CTX_free(ctx);
344       EVP_MAC_free(mac);
345       exit(0);
346
347    err:
348       EVP_MAC_CTX_free(ctx);
349       EVP_MAC_free(mac);
350       fprintf(stderr, "Something went wrong\n");
351       ERR_print_errors_fp(stderr);
352       exit (1);
353   }
354
355 A run of this program, called with correct environment variables, can
356 look like this:
357
358   $ MY_MAC=cmac MY_KEY=secret0123456789 MY_MAC_CIPHER=aes-128-cbc \
359     LD_LIBRARY_PATH=. ./foo < foo.c
360   Result: ECCAAFF041B22A2299EB90A1B53B6D45
361
362 (in this example, that program was stored in F<foo.c> and compiled to
363 F<./foo>)
364
365 =head1 SEE ALSO
366
367 L<property(7)>
368 L<OSSL_PARAM(3)>,
369 L<EVP_MAC_BLAKE2(7)>,
370 L<EVP_MAC_CMAC(7)>,
371 L<EVP_MAC_GMAC(7)>,
372 L<EVP_MAC_HMAC(7)>,
373 L<EVP_MAC_KMAC(7)>,
374 L<EVP_MAC_SIPHASH(7)>,
375 L<EVP_MAC_POLY1305(7)>
376
377 =head1 HISTORY
378
379 These functions were added in OpenSSL 3.0.
380
381 =head1 COPYRIGHT
382
383 Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
384
385 Licensed under the Apache License 2.0 (the "License").  You may not use
386 this file except in compliance with the License.  You can obtain a copy
387 in the file LICENSE in the source distribution or at
388 L<https://www.openssl.org/source/license.html>.
389
390 =cut