5 EVP_MAC, EVP_MAC_fetch, EVP_MAC_up_ref, EVP_MAC_free, EVP_MAC_name,
6 EVP_MAC_get_params, EVP_MAC_gettable_params,
7 EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_free, EVP_MAC_CTX_dup,
8 EVP_MAC_CTX_mac, EVP_MAC_CTX_get_params, EVP_MAC_CTX_set_params,
9 EVP_MAC_size, EVP_MAC_init, EVP_MAC_update, EVP_MAC_final,
10 EVP_MAC_CTX_gettable_params, EVP_MAC_CTX_settable_params
15 #include <openssl/evp.h>
17 typedef struct evp_mac_st EVP_MAC;
18 typedef struct evp_mac_ctx_st EVP_MAC_CTX;
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);
25 int EVP_MAC_get_params(EVP_MAC *mac, OSSL_PARAM params[]);
27 EVP_MAC_CTX *EVP_MAC_CTX_new(EVP_MAC *mac);
28 void EVP_MAC_CTX_free(EVP_MAC_CTX *ctx);
29 EVP_MAC_CTX *EVP_MAC_CTX_dup(const EVP_MAC_CTX *src);
30 EVP_MAC *EVP_MAC_CTX_mac(EVP_MAC_CTX *ctx);
31 int EVP_MAC_CTX_get_params(EVP_MAC_CTX *ctx, OSSL_PARAM params[]);
32 int EVP_MAC_CTX_set_params(EVP_MAC_CTX *ctx, const OSSL_PARAM params[]);
34 size_t EVP_MAC_size(EVP_MAC_CTX *ctx);
35 int EVP_MAC_init(EVP_MAC_CTX *ctx);
36 int EVP_MAC_update(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
37 int EVP_MAC_final(EVP_MAC_CTX *ctx,
38 unsigned char *out, size_t *outl, size_t outsize);
40 const OSSL_PARAM *EVP_MAC_gettable_params(const EVP_MAC *mac);
41 const OSSL_PARAM *EVP_MAC_CTX_gettable_params(const EVP_MAC *mac);
42 const OSSL_PARAM *EVP_MAC_CTX_settable_params(const EVP_MAC *mac);
46 These types and functions help the application to calculate MACs of
47 different types and with different underlying algorithms if there are
50 MACs are a bit complex insofar that some of them use other algorithms
51 for actual computation. HMAC uses a digest, and CMAC uses a cipher.
52 Therefore, there are sometimes two contexts to keep track of, one for
53 the MAC algorithm itself and one for the underlying computation
54 algorithm if there is one.
56 To make things less ambiguous, this manual talks about a "context" or
57 "MAC context", which is to denote the MAC level context, and about a
58 "underlying context", or "computation context", which is to denote the
59 context for the underlying computation algorithm if there is one.
63 B<EVP_MAC> is a type that holds the implementation of a MAC.
65 B<EVP_MAC_CTX> is a context type that holds internal MAC information
66 as well as a reference to a computation context, for those MACs that
67 rely on an underlying computation algorithm.
69 =head2 Algorithm implementation fetching
71 EVP_MAC_fetch() fetches an implementation of a MAC I<algorithm>, given
72 a library context I<libctx> and a set of I<properties>.
73 See L<provider(7)/Fetching algorithms> for further information.
75 The returned value must eventually be freed with
78 EVP_MAC_up_ref() increments the reference count of an already fetched
81 EVP_MAC_free() frees a fetched algorithm.
82 NULL is a valid parameter, for which this function is a no-op.
84 =head2 Context manipulation functions
86 EVP_MAC_CTX_new() creates a new context for the MAC type I<mac>.
87 The created context can then be used with most other functions
90 EVP_MAC_CTX_free() frees the contents of the context, including an
91 underlying context if there is one, as well as the context itself.
92 NULL is a valid parameter, for which this function is a no-op.
94 EVP_MAC_CTX_dup() duplicates the I<src> context and returns a newly allocated
97 EVP_MAC_CTX_mac() returns the B<EVP_MAC> associated with the context
100 =head2 Computing functions
102 EVP_MAC_init() sets up the underlying context with information given
103 through diverse controls.
104 This should be called before calling EVP_MAC_update() and
107 EVP_MAC_update() adds I<datalen> bytes from I<data> to the MAC input.
109 EVP_MAC_final() does the final computation and stores the result in
110 the memory pointed at by I<out> of size I<outsize>, and sets the number
111 of bytes written in I<*outl> at.
112 If I<out> is B<NULL> or I<outsize> is too small, then no computation
114 To figure out what the output length will be and allocate space for it
115 dynamically, simply call with I<out> being B<NULL> and I<outl>
116 pointing at a valid location, then allocate space and make a second
117 call with I<out> pointing at the allocated space.
119 EVP_MAC_get_params() retrieves details about the implementation
121 The set of parameters given with I<params> determine exactly what
122 parameters should be retrieved.
123 Note that a parameter that is unknown in the underlying context is
126 EVP_MAC_CTX_get_params() retrieves chosen parameters, given the
127 context I<ctx> and its underlying context.
128 The set of parameters given with I<params> determine exactly what
129 parameters should be retrieved.
130 Note that a parameter that is unknown in the underlying context is
133 EVP_MAC_CTX_set_params() passes chosen parameters to the underlying
134 context, given a context I<ctx>.
135 The set of parameters given with I<params> determine exactly what
136 parameters are passed down.
137 Note that a parameter that is unknown in the underlying context is
139 Also, what happens when a needed parameter isn't passed down is
140 defined by the implementation.
142 EVP_MAC_gettable_params(), EVP_MAC_CTX_gettable_params() and
143 EVP_MAC_CTX_settable_params() get a constant B<OSSL_PARAM> array that
144 decribes the retrievable and settable parameters, i.e. parameters that
145 can be used with EVP_MAC_CTX_get_params(), EVP_MAC_CTX_get_params()
146 and EVP_MAC_CTX_set_params(), respectively.
147 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
149 =head2 Information functions
151 EVP_MAC_size() returns the MAC output size for the given context.
153 EVP_MAC_name() returns the name of the given MAC implementation.
155 =head1 PARAMETER NAMES
157 The standard parameter names are:
161 =item OSSL_MAC_PARAM_KEY ("key") <octet string>
163 Its value is the MAC key as an array of bytes.
165 For MACs that use an underlying computation algorithm, the algorithm
166 must be set first, see parameter names "algorithm" below.
168 =item OSSL_MAC_PARAM_IV ("iv") <octet string>
170 Some MAC implementations require an IV, this parameter sets the IV.
172 =item OSSL_MAC_PARAM_CUSTOM ("custom") <octet string>
174 Some MAC implementations (KMAC, BLAKE2) accept a Customization String,
175 this parameter sets the Customization String. The default value is the
178 =item OSSL_MAC_PARAM_SALT ("salt") <octet string>
180 This option is used by BLAKE2 MAC.
182 =item OSSL_MAC_PARAM_XOF ("xof") <int>
184 It's a simple flag, the value 0 or 1 are expected.
186 This option is used by KMAC.
188 =item OSSL_MAC_PARAM_FLAGS ("flags") <int>
190 These will set the MAC flags to the given numbers.
191 Some MACs do not support this option.
193 =item OSSL_MAC_PARAM_ENGINE ("engine") <utf8string>
195 =item OSSL_MAC_PARAM_MD ("md") <utf8string>
197 =item OSSL_MAC_PARAM_DIGEST ("digest") <utf8string>
199 =item OSSL_MAC_PARAM_CIPHER ("cipher") <utf8string>
201 =item OSSL_MAC_PARAM_ALGORITHM ("algorithm") <utf8string>
203 For MAC implementations that use an underlying computation algorithm,
204 these parameters set what the algorithm should be, and the engine that
205 implements the algorithm if needed.
207 The value is always the name of the intended engine or algorithm.
209 Note that not all algorithms may support all digests.
210 HMAC does not support variable output length digests such as SHAKE128
213 Also note that OSSL_MAC_PARAM_ALGORITHM can be use generically instead
214 of OSSL_MAC_PARAM_MD, OSSL_MAC_PARAM_DIGEST or OSSL_MAC_PARAM_CIPHER,
215 and that OSSL_MAC_PARAM_MD and OSSL_MAC_PARAM_DIGEST are also interchangable.
217 =item OSSL_MAC_PARAM_SIZE <unsigned int>
219 For MAC implementations that support it, set the output size that
220 EVP_MAC_final() should produce.
221 The allowed sizes vary between MAC implementations.
225 All these parameters should be used before the calls to any of
226 EVP_MAC_init(), EVP_MAC_update() and EVP_MAC_final() for a full
228 Anything else may give undefined results.
232 EVP_MAC_fetch() returns a pointer to a newly fetched EVP_MAC, or
233 NULL if allocation failed.
235 EVP_MAC_up_ref() returns 1 on success, 0 on error.
237 EVP_MAC_free() returns nothing at all.
239 EVP_MAC_name() returns the name of the MAC, or NULL if NULL was
242 EVP_MAC_CTX_new() and EVP_MAC_CTX_dup() return a pointer to a newly
243 created EVP_MAC_CTX, or NULL if allocation failed.
245 EVP_MAC_CTX_free() returns nothing at all.
247 EVP_MAC_CTX_get_params() and EVP_MAC_CTX_set_params() return 1 on
250 EVP_MAC_init(), EVP_MAC_update(), and EVP_MAC_final() return 1 on success, 0
253 EVP_MAC_size() returns the expected output size, or 0 if it isn't
255 If it isn't set, a call to EVP_MAC_init() should get it set.
266 #include <openssl/evp.h>
267 #include <openssl/err.h>
268 #include <openssl/params.h>
271 EVP_MAC *mac = EVP_MAC_fetch(NULL, getenv("MY_MAC"), NULL);
272 const char *cipher = getenv("MY_MAC_CIPHER");
273 const char *digest = getenv("MY_MAC_DIGEST");
274 const char *key = getenv("MY_KEY");
275 EVP_MAC_CTX *ctx = NULL;
277 unsigned char buf[4096];
283 OSSL_PARAM params[4];
288 OSSL_PARAM_construct_utf8_string("cipher", cipher,
289 strlen(cipher) + 1, NULL);
292 OSSL_PARAM_construct_utf8_string("digest", digest,
293 strlen(digest) + 1, NULL);
295 OSSL_PARAM_construct_octet_string("key", key, strlen(key), NULL);
296 params[params_n] = OSSL_PARAM_construct_end();
300 || (ctx = EVP_MAC_CTX_new(mac)) == NULL
301 || EVP_MAC_CTX_set_params(ctx, params) <= 0)
304 if (!EVP_MAC_init(ctx))
307 while ( (read_l = read(STDIN_FILENO, buf, sizeof(buf))) < 0) {
308 if (!EVP_MAC_update(ctx, buf, read_l))
312 if (!EVP_MAC_final(ctx, buf, &final_l))
316 for (i = 0; i < final_l; i++)
317 printf("%02X", buf[i]);
320 EVP_MAC_CTX_free(ctx);
325 EVP_MAC_CTX_free(ctx);
327 fprintf(stderr, "Something went wrong\n");
328 ERR_print_errors_fp(stderr);
332 A run of this program, called with correct environment variables, can
335 $ MY_MAC=cmac MY_KEY=secret0123456789 MY_MAC_CIPHER=aes-128-cbc \
336 LD_LIBRARY_PATH=. ./foo < foo.c
337 Result: ECCAAFF041B22A2299EB90A1B53B6D45
339 (in this example, that program was stored in F<foo.c> and compiled to
346 L<EVP_MAC_BLAKE2(7)>,
351 L<EVP_MAC_SIPHASH(7)>,
352 L<EVP_MAC_POLY1305(7)>
356 These functions were added in OpenSSL 3.0.
360 Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
362 Licensed under the Apache License 2.0 (the "License"). You may not use
363 this file except in compliance with the License. You can obtain a copy
364 in the file LICENSE in the source distribution or at
365 L<https://www.openssl.org/source/license.html>.