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