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