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, EVP_MAC_is_a,
   6 EVP_MAC_number, EVP_MAC_name, EVP_MAC_names_do_all, EVP_MAC_description,
   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_CTX_get_mac_size, EVP_Q_mac,
  11 EVP_MAC_init, EVP_MAC_update, EVP_MAC_final, EVP_MAC_finalXOF,
  12 EVP_MAC_gettable_ctx_params, EVP_MAC_settable_ctx_params,
  13 EVP_MAC_CTX_gettable_params, EVP_MAC_CTX_settable_params,
  14 EVP_MAC_do_all_provided - EVP MAC routines
  15
  16 =head1 SYNOPSIS
  17
  18  #include <openssl/evp.h>
  19
  20  typedef struct evp_mac_st EVP_MAC;
  21  typedef struct evp_mac_ctx_st EVP_MAC_CTX;
  22
  23  EVP_MAC *EVP_MAC_fetch(OSSL_LIB_CTX *libctx, const char *algorithm,
  24                         const char *properties);
  25  int EVP_MAC_up_ref(EVP_MAC *mac);
  26  void EVP_MAC_free(EVP_MAC *mac);
  27  int EVP_MAC_is_a(const EVP_MAC *mac, const char *name);
  28  int EVP_MAC_number(const EVP_MAC *mac);
  29  const char *EVP_MAC_name(const EVP_MAC *mac);
  30  int EVP_MAC_names_do_all(const EVP_MAC *mac,
  31                           void (*fn)(const char *name, void *data),
  32                           void *data);
  33  const char *EVP_MAC_description(const EVP_MAC *mac);
  34  const OSSL_PROVIDER *EVP_MAC_provider(const EVP_MAC *mac);
  35  int EVP_MAC_get_params(EVP_MAC *mac, OSSL_PARAM params[]);
  36
  37  EVP_MAC_CTX *EVP_MAC_CTX_new(EVP_MAC *mac);
  38  void EVP_MAC_CTX_free(EVP_MAC_CTX *ctx);
  39  EVP_MAC_CTX *EVP_MAC_CTX_dup(const EVP_MAC_CTX *src);
  40  EVP_MAC *EVP_MAC_CTX_mac(EVP_MAC_CTX *ctx);
  41  int EVP_MAC_CTX_get_params(EVP_MAC_CTX *ctx, OSSL_PARAM params[]);
  42  int EVP_MAC_CTX_set_params(EVP_MAC_CTX *ctx, const OSSL_PARAM params[]);
  43
  44  size_t EVP_MAC_CTX_get_mac_size(EVP_MAC_CTX *ctx);
  45  unsigned char *EVP_Q_mac(OSSL_LIB_CTX *libctx, const char *name, const char *propq,
  46                           const char *subalg, const OSSL_PARAM *params,
  47                           const void *key, size_t keylen,
  48                           const unsigned char *data, size_t datalen,
  49                           unsigned char *out, size_t outsize, unsigned int *outlen);
  50  int EVP_MAC_init(EVP_MAC_CTX *ctx, const unsigned char *key, size_t keylen,
  51                   const OSSL_PARAM params[]);
  52  int EVP_MAC_update(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
  53  int EVP_MAC_final(EVP_MAC_CTX *ctx,
  54                    unsigned char *out, size_t *outl, size_t outsize);
  55  int EVP_MAC_finalXOF(EVP_MAC_CTX *ctx, unsigned char *out, size_t outsize);
  56
  57  const OSSL_PARAM *EVP_MAC_gettable_params(const EVP_MAC *mac);
  58  const OSSL_PARAM *EVP_MAC_gettable_ctx_params(const EVP_MAC *mac);
  59  const OSSL_PARAM *EVP_MAC_settable_ctx_params(const EVP_MAC *mac);
  60  const OSSL_PARAM *EVP_MAC_CTX_gettable_params(EVP_MAC_CTX *ctx);
  61  const OSSL_PARAM *EVP_MAC_CTX_settable_params(EVP_MAC_CTX *ctx);
  62
  63  void EVP_MAC_do_all_provided(OSSL_LIB_CTX *libctx,
  64                               void (*fn)(EVP_MAC *mac, void *arg),
  65                               void *arg);
  66
  67 =head1 DESCRIPTION
  68
  69 These types and functions help the application to calculate MACs of
  70 different types and with different underlying algorithms if there are
  71 any.
  72
  73 MACs are a bit complex insofar that some of them use other algorithms
  74 for actual computation.  HMAC uses a digest, and CMAC uses a cipher.
  75 Therefore, there are sometimes two contexts to keep track of, one for
  76 the MAC algorithm itself and one for the underlying computation
  77 algorithm if there is one.
  78
  79 To make things less ambiguous, this manual talks about a "context" or
  80 "MAC context", which is to denote the MAC level context, and about a
  81 "underlying context", or "computation context", which is to denote the
  82 context for the underlying computation algorithm if there is one.
  83
  84 =head2 Types
  85
  86 B<EVP_MAC> is a type that holds the implementation of a MAC.
  87
  88 B<EVP_MAC_CTX> is a context type that holds internal MAC information
  89 as well as a reference to a computation context, for those MACs that
  90 rely on an underlying computation algorithm.
  91
  92 =head2 Algorithm implementation fetching
  93
  94 EVP_MAC_fetch() fetches an implementation of a MAC I<algorithm>, given
  95 a library context I<libctx> and a set of I<properties>.
  96 See L<crypto(7)/ALGORITHM FETCHING> for further information.
  97
  98 See L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)> for the list
  99 of algorithms supported by the default provider.
 100
 101 The returned value must eventually be freed with
 102 L<EVP_MAC_free(3)>.
 103
 104 EVP_MAC_up_ref() increments the reference count of an already fetched
 105 MAC.
 106
 107 EVP_MAC_free() frees a fetched algorithm.
 108 NULL is a valid parameter, for which this function is a no-op.
 109
 110 =head2 Context manipulation functions
 111
 112 EVP_MAC_CTX_new() creates a new context for the MAC type I<mac>.
 113 The created context can then be used with most other functions
 114 described here.
 115
 116 EVP_MAC_CTX_free() frees the contents of the context, including an
 117 underlying context if there is one, as well as the context itself.
 118 NULL is a valid parameter, for which this function is a no-op.
 119
 120 EVP_MAC_CTX_dup() duplicates the I<src> context and returns a newly allocated
 121 context.
 122
 123 EVP_MAC_CTX_mac() returns the B<EVP_MAC> associated with the context
 124 I<ctx>.
 125
 126 =head2 Computing functions
 127
 128 EVP_Q_mac() computes the message authentication code
 129 of I<data> with length I<datalen>
 130 using the MAC algorithm I<name> and the key I<key> with length I<keylen>.
 131 The MAC algorithm is fetched using any given I<libctx> and property query
 132 string I<propq>. It takes parameters I<subalg> and further I<params>,
 133 both of which may be NULL if not needed.
 134 If I<out> is not NULL, it places the result in the memory pointed at by I<out>,
 135 but only if I<outsize> is sufficient (otherwise no computation is made).
 136 If I<out> is NULL, it allocates and uses a buffer of suitable length,
 137 which will be returned on success and must be freed by the caller.
 138 In either case, also on error,
 139 it assigns the number of bytes written to I<*outlen> unless I<outlen> is NULL.
 140
 141 EVP_MAC_init() sets up the underlying context I<ctx> with information given
 142 via the I<key> and I<params> arguments.  The MAC I<key> has a length of
 143 I<keylen> and the parameters in I<params> are processed before setting
 144 the key.  If I<key> is NULL, the key must be set via I<params> either
 145 as part of this call or separately using EVP_MAC_CTX_set_params().
 146 Providing non-NULL I<params> to this function is equivalent to calling
 147 EVP_MAC_CTX_set_params() with those I<params> for the same I<ctx> beforehand.
 148
 149 EVP_MAC_init() should be called before EVP_MAC_update() and EVP_MAC_final().
 150
 151 EVP_MAC_update() adds I<datalen> bytes from I<data> to the MAC input.
 152
 153 EVP_MAC_final() does the final computation and stores the result in
 154 the memory pointed at by I<out> of size I<outsize>, and sets the number
 155 of bytes written in I<*outl> at.
 156 If I<out> is NULL or I<outsize> is too small, then no computation
 157 is made.
 158 To figure out what the output length will be and allocate space for it
 159 dynamically, simply call with I<out> being NULL and I<outl>
 160 pointing at a valid location, then allocate space and make a second
 161 call with I<out> pointing at the allocated space.
 162
 163 EVP_MAC_finalXOF() does the final computation for an XOF based MAC and stores
 164 the result in the memory pointed at by I<out> of size I<outsize>.
 165
 166 EVP_MAC_get_params() retrieves details about the implementation
 167 I<mac>.
 168 The set of parameters given with I<params> determine exactly what
 169 parameters should be retrieved.
 170 Note that a parameter that is unknown in the underlying context is
 171 simply ignored.
 172
 173 EVP_MAC_CTX_get_params() retrieves chosen parameters, given the
 174 context I<ctx> and its underlying context.
 175 The set of parameters given with I<params> determine exactly what
 176 parameters should be retrieved.
 177 Note that a parameter that is unknown in the underlying context is
 178 simply ignored.
 179
 180 EVP_MAC_CTX_set_params() passes chosen parameters to the underlying
 181 context, given a context I<ctx>.
 182 The set of parameters given with I<params> determine exactly what
 183 parameters are passed down.
 184 If I<params> are NULL, the unterlying context should do nothing and return 1.
 185 Note that a parameter that is unknown in the underlying context is
 186 simply ignored.
 187 Also, what happens when a needed parameter isn't passed down is
 188 defined by the implementation.
 189
 190 EVP_MAC_gettable_params() returns an B<OSSL_PARAM> array that describes
 191 the retrievable and settable parameters.  EVP_MAC_gettable_params()
 192 returns parameters that can be used with EVP_MAC_get_params().
 193 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
 194
 195 EVP_MAC_gettable_ctx_params() and EVP_MAC_CTX_gettable_params()
 196 return constant B<OSSL_PARAM> arrays that describe the retrievable
 197 parameters that can be used with EVP_MAC_CTX_get_params().
 198 EVP_MAC_gettable_ctx_params() returns the parameters that can be retrieved
 199 from the algorithm, whereas EVP_MAC_CTX_gettable_params() returns
 200 the parameters that can be retrieved in the context's current state.
 201 See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as a parameter descriptor.
 202
 203 EVP_MAC_settable_ctx_params() and EVP_MAC_CTX_settable_params() return
 204 constant B<OSSL_PARAM> arrays that describe the settable parameters that
 205 can be used with EVP_MAC_CTX_set_params().  EVP_MAC_settable_ctx_params()
 206 returns the parameters that can be retrieved from the algorithm,
 207 whereas EVP_MAC_CTX_settable_params() returns the parameters that can
 208 be retrieved in the context's current state.  See L<OSSL_PARAM(3)>
 209 for the use of B<OSSL_PARAM> as a parameter descriptor.
 210
 211 =head2 Information functions
 212
 213 EVP_MAC_CTX_get_mac_size() returns the MAC output size for the given context.
 214
 215 EVP_MAC_is_a() checks if the given I<mac> is an implementation of an
 216 algorithm that's identifiable with I<name>.
 217
 218 EVP_MAC_provider() returns the provider that holds the implementation
 219 of the given I<mac>.
 220
 221 EVP_MAC_do_all_provided() traverses all MAC implemented by all activated
 222 providers in the given library context I<libctx>, and for each of the
 223 implementations, calls the given function I<fn> with the implementation method
 224 and the given I<arg> as argument.
 225
 226 EVP_MAC_number() returns the internal dynamic number assigned to
 227 I<mac>.
 228
 229 EVP_MAC_name() return the name of the given MAC.  For fetched MACs
 230 with multiple names, only one of them is returned; it's
 231 recommended to use EVP_MAC_names_do_all() instead.
 232
 233 EVP_MAC_names_do_all() traverses all names for I<mac>, and calls
 234 I<fn> with each name and I<data>.
 235
 236 EVP_MAC_description() returns a description of the I<mac>, meant for display
 237 and human consumption.  The description is at the discretion of the mac
 238 implementation.
 239
 240 =head1 PARAMETERS
 241
 242 Parameters are identified by name as strings, and have an expected
 243 data type and maximum size.
 244 OpenSSL has a set of macros for parameter names it expects to see in
 245 its own MAC implementations.
 246 Here, we show all three, the OpenSSL macro for the parameter name, the
 247 name in string form, and a type description.
 248
 249 The standard parameter names are:
 250
 251 =over 4
 252
 253 =item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string>
 254
 255 Its value is the MAC key as an array of bytes.
 256
 257 For MACs that use an underlying computation algorithm, the algorithm
 258 must be set first, see parameter names "algorithm" below.
 259
 260 =item "iv" (B<OSSL_MAC_PARAM_IV>) <octet string>
 261
 262 Some MAC implementations require an IV, this parameter sets the IV.
 263
 264 =item "custom" (B<OSSL_MAC_PARAM_CUSTOM>) <octet string>
 265
 266 Some MAC implementations (KMAC, BLAKE2) accept a Customization String,
 267 this parameter sets the Customization String. The default value is the
 268 empty string.
 269
 270 =item "salt" (B<OSSL_MAC_PARAM_SALT>) <octet string>
 271
 272 This option is used by BLAKE2 MAC.
 273
 274 =item "xof" (B<OSSL_MAC_PARAM_XOF>) <integer>
 275
 276 It's a simple flag, the value 0 or 1 are expected.
 277
 278 This option is used by KMAC.
 279
 280 =item "digest-noinit" (B<OSSL_MAC_PARAM_DIGEST_NOINIT>) <integer>
 281
 282 A simple flag to set the MAC digest to not initialise the
 283 implementation specific data. The value 0 or 1 is expected.
 284
 285 This option is used by HMAC.
 286
 287 =item "digest-oneshot" (B<OSSL_MAC_PARAM_DIGEST_ONESHOT>) <integer>
 288
 289 A simple flag to set the MAC digest to be a oneshot operation.
 290 The value 0 or 1 is expected.
 291
 292 This option is used by HMAC.
 293
 294 =item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string>
 295
 296 =item "digest" (B<OSSL_MAC_PARAM_DIGEST>) <UTF8 string>
 297
 298 =item "cipher" (B<OSSL_MAC_PARAM_CIPHER>) <UTF8 string>
 299
 300 For MAC implementations that use an underlying computation cipher or
 301 digest, these parameters set what the algorithm should be.
 302
 303 The value is always the name of the intended algorithm,
 304 or the properties.
 305
 306 Note that not all algorithms may support all digests.
 307 HMAC does not support variable output length digests such as SHAKE128
 308 or SHAKE256.
 309
 310 =item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
 311
 312 For MAC implementations that support it, set the output size that
 313 EVP_MAC_final() should produce.
 314 The allowed sizes vary between MAC implementations, but must never exceed
 315 what can be given with a B<size_t>.
 316
 317 =item "tls-data-size" (B<OSSL_MAC_PARAM_TLS_DATA_SIZE>) <unsigned integer>
 318
 319 This parameter is only supported by HMAC. If set then special handling is
 320 activated for calculating the MAC of a received mac-then-encrypt TLS record
 321 where variable length record padding has been used (as in the case of CBC mode
 322 ciphersuites). The value represents the total length of the record that is
 323 having the MAC calculated including the received MAC and the record padding.
 324
 325 When used EVP_MAC_update must be called precisely twice. The first time with
 326 the 13 bytes of TLS "header" data, and the second time with the entire record
 327 including the MAC itself and any padding. The entire record length must equal
 328 the value passed in the "tls-data-size" parameter. The length passed in the
 329 B<datalen> parameter to EVP_MAC_update() should be equal to the length of the
 330 record after the MAC and any padding has been removed.
 331
 332 =back
 333
 334 All these parameters should be used before the calls to any of
 335 EVP_MAC_init(), EVP_MAC_update() and EVP_MAC_final() for a full
 336 computation.
 337 Anything else may give undefined results.
 338
 339 =head1 NOTES
 340
 341 The MAC life-cycle is described in L<life_cycle-mac(7)>.  In the future,
 342 the transitions described there will be enforced.  When this is done, it will
 343 not be considered a breaking change to the API.
 344
 345
 346 =head1 RETURN VALUES
 347
 348 EVP_MAC_fetch() returns a pointer to a newly fetched B<EVP_MAC>, or
 349 NULL if allocation failed.
 350
 351 EVP_MAC_up_ref() returns 1 on success, 0 on error.
 352
 353 EVP_MAC_names_do_all() returns 1 if the callback was called for all names. A
 354 return value of 0 means that the callback was not called for any names.
 355
 356 EVP_MAC_free() returns nothing at all.
 357
 358 EVP_MAC_is_a() returns 1 if the given method can be identified with
 359 the given name, otherwise 0.
 360
 361 EVP_MAC_name() returns a name of the MAC, or NULL on error.
 362
 363 EVP_MAC_provider() returns a pointer to the provider for the MAC, or
 364 NULL on error.
 365
 366 EVP_MAC_CTX_new() and EVP_MAC_CTX_dup() return a pointer to a newly
 367 created EVP_MAC_CTX, or NULL if allocation failed.
 368
 369 EVP_MAC_CTX_free() returns nothing at all.
 370
 371 EVP_MAC_CTX_get_params() and EVP_MAC_CTX_set_params() return 1 on
 372 success, 0 on error.
 373
 374 EVP_Q_mac() returns a pointer to the computed MAC value, or NULL on error.
 375
 376 EVP_MAC_init(), EVP_MAC_update(), EVP_MAC_final(), and EVP_MAC_finalXOF()
 377 return 1 on success, 0 on error.
 378
 379 EVP_MAC_CTX_get_mac_size() returns the expected output size, or 0 if it isn't set.
 380 If it isn't set, a call to EVP_MAC_init() should get it set.
 381
 382 EVP_MAC_do_all_provided() returns nothing at all.
 383
 384 =head1 EXAMPLES
 385
 386   #include <stdlib.h>
 387   #include <stdio.h>
 388   #include <string.h>
 389   #include <stdarg.h>
 390   #include <unistd.h>
 391
 392   #include <openssl/evp.h>
 393   #include <openssl/err.h>
 394   #include <openssl/params.h>
 395
 396   int main() {
 397       EVP_MAC *mac = EVP_MAC_fetch(NULL, getenv("MY_MAC"), NULL);
 398       const char *cipher = getenv("MY_MAC_CIPHER");
 399       const char *digest = getenv("MY_MAC_DIGEST");
 400       const char *key = getenv("MY_KEY");
 401       EVP_MAC_CTX *ctx = NULL;
 402
 403       unsigned char buf[4096];
 404       size_t read_l;
 405       size_t final_l;
 406
 407       size_t i;
 408
 409       OSSL_PARAM params[3];
 410       size_t params_n = 0;
 411
 412       if (cipher != NULL)
 413           params[params_n++] =
 414               OSSL_PARAM_construct_utf8_string("cipher", (char*)cipher, 0);
 415       if (digest != NULL)
 416           params[params_n++] =
 417               OSSL_PARAM_construct_utf8_string("digest", (char*)digest, 0);
 418       params[params_n] = OSSL_PARAM_construct_end();
 419
 420       if (mac == NULL
 421           || key == NULL
 422           || (ctx = EVP_MAC_CTX_new(mac)) == NULL
 423           || !EVP_MAC_init(ctx, (const unsigned char *)key, strlen(key),
 424                            params))
 425           goto err;
 426
 427       while ( (read_l = read(STDIN_FILENO, buf, sizeof(buf))) > 0) {
 428           if (!EVP_MAC_update(ctx, buf, read_l))
 429               goto err;
 430       }
 431
 432       if (!EVP_MAC_final(ctx, buf, &final_l, sizeof(buf)))
 433           goto err;
 434
 435       printf("Result: ");
 436       for (i = 0; i < final_l; i++)
 437           printf("%02X", buf[i]);
 438       printf("\n");
 439
 440       EVP_MAC_CTX_free(ctx);
 441       EVP_MAC_free(mac);
 442       exit(0);
 443
 444    err:
 445       EVP_MAC_CTX_free(ctx);
 446       EVP_MAC_free(mac);
 447       fprintf(stderr, "Something went wrong\n");
 448       ERR_print_errors_fp(stderr);
 449       exit (1);
 450   }
 451
 452 A run of this program, called with correct environment variables, can
 453 look like this:
 454
 455   $ MY_MAC=cmac MY_KEY=secret0123456789 MY_MAC_CIPHER=aes-128-cbc \
 456     LD_LIBRARY_PATH=. ./foo < foo.c
 457   Result: C5C06683CD9DDEF904D754505C560A4E
 458
 459 (in this example, that program was stored in F<foo.c> and compiled to
 460 F<./foo>)
 461
 462 =head1 SEE ALSO
 463
 464 L<property(7)>
 465 L<OSSL_PARAM(3)>,
 466 L<EVP_MAC-BLAKE2(7)>,
 467 L<EVP_MAC-CMAC(7)>,
 468 L<EVP_MAC-GMAC(7)>,
 469 L<EVP_MAC-HMAC(7)>,
 470 L<EVP_MAC-KMAC(7)>,
 471 L<EVP_MAC-Siphash(7)>,
 472 L<EVP_MAC-Poly1305(7)>,
 473 L<provider-mac(7)>,
 474 L<life_cycle-mac(7)>
 475
 476 =head1 HISTORY
 477
 478 These functions were added in OpenSSL 3.0.
 479
 480 =head1 COPYRIGHT
 481
 482 Copyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved.
 483
 484 Licensed under the Apache License 2.0 (the "License").  You may not use
 485 this file except in compliance with the License.  You can obtain a copy
 486 in the file LICENSE in the source distribution or at
 487 L<https://www.openssl.org/source/license.html>.
 488
 489 =cut