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  void 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_free() returns nothing at all.
 295
 296 EVP_MAC_is_a() returns 1 if the given method can be identified with
 297 the given name, otherwise 0.
 298
 299 EVP_MAC_name() returns a name of the MAC, or NULL on error.
 300
 301 EVP_MAC_provider() returns a pointer to the provider for the MAC, or
 302 NULL on error.
 303
 304 EVP_MAC_CTX_new() and EVP_MAC_CTX_dup() return a pointer to a newly
 305 created EVP_MAC_CTX, or NULL if allocation failed.
 306
 307 EVP_MAC_CTX_free() returns nothing at all.
 308
 309 EVP_MAC_CTX_get_params() and EVP_MAC_CTX_set_params() return 1 on
 310 success, 0 on error.
 311
 312 EVP_MAC_init(), EVP_MAC_update(), and EVP_MAC_final() return 1 on success, 0
 313 on error.
 314
 315 EVP_MAC_CTX_get_mac_size() returns the expected output size, or 0 if it isn't set.
 316 If it isn't set, a call to EVP_MAC_init() should get it set.
 317
 318 EVP_MAC_do_all_provided() returns nothing at all.
 319
 320 =head1 EXAMPLES
 321
 322   #include <stdlib.h>
 323   #include <stdio.h>
 324   #include <string.h>
 325   #include <stdarg.h>
 326   #include <unistd.h>
 327
 328   #include <openssl/evp.h>
 329   #include <openssl/err.h>
 330   #include <openssl/params.h>
 331
 332   int main() {
 333       EVP_MAC *mac = EVP_MAC_fetch(NULL, getenv("MY_MAC"), NULL);
 334       const char *cipher = getenv("MY_MAC_CIPHER");
 335       const char *digest = getenv("MY_MAC_DIGEST");
 336       const char *key = getenv("MY_KEY");
 337       EVP_MAC_CTX *ctx = NULL;
 338
 339       unsigned char buf[4096];
 340       size_t read_l;
 341       size_t final_l;
 342
 343       size_t i;
 344
 345       OSSL_PARAM params[4];
 346       size_t params_n = 0;
 347
 348       if (cipher != NULL)
 349           params[params_n++] =
 350               OSSL_PARAM_construct_utf8_string("cipher", (char*)cipher, 0);
 351       if (digest != NULL)
 352           params[params_n++] =
 353               OSSL_PARAM_construct_utf8_string("digest", (char*)digest, 0);
 354       params[params_n++] =
 355           OSSL_PARAM_construct_octet_string("key", (void*)key, strlen(key));
 356       params[params_n] = OSSL_PARAM_construct_end();
 357
 358       if (mac == NULL
 359           || key == NULL
 360           || (ctx = EVP_MAC_CTX_new(mac)) == NULL
 361           || EVP_MAC_CTX_set_params(ctx, params) <= 0)
 362           goto err;
 363
 364       if (!EVP_MAC_init(ctx))
 365           goto err;
 366
 367       while ( (read_l = read(STDIN_FILENO, buf, sizeof(buf))) > 0) {
 368           if (!EVP_MAC_update(ctx, buf, read_l))
 369               goto err;
 370       }
 371
 372       if (!EVP_MAC_final(ctx, buf, &final_l, sizeof(buf)))
 373           goto err;
 374
 375       printf("Result: ");
 376       for (i = 0; i < final_l; i++)
 377           printf("%02X", buf[i]);
 378       printf("\n");
 379
 380       EVP_MAC_CTX_free(ctx);
 381       EVP_MAC_free(mac);
 382       exit(0);
 383
 384    err:
 385       EVP_MAC_CTX_free(ctx);
 386       EVP_MAC_free(mac);
 387       fprintf(stderr, "Something went wrong\n");
 388       ERR_print_errors_fp(stderr);
 389       exit (1);
 390   }
 391
 392 A run of this program, called with correct environment variables, can
 393 look like this:
 394
 395   $ MY_MAC=cmac MY_KEY=secret0123456789 MY_MAC_CIPHER=aes-128-cbc \
 396     LD_LIBRARY_PATH=. ./foo < foo.c
 397   Result: C5C06683CD9DDEF904D754505C560A4E
 398
 399 (in this example, that program was stored in F<foo.c> and compiled to
 400 F<./foo>)
 401
 402 =head1 SEE ALSO
 403
 404 L<property(7)>
 405 L<OSSL_PARAM(3)>,
 406 L<EVP_MAC-BLAKE2(7)>,
 407 L<EVP_MAC-CMAC(7)>,
 408 L<EVP_MAC-GMAC(7)>,
 409 L<EVP_MAC-HMAC(7)>,
 410 L<EVP_MAC-KMAC(7)>,
 411 L<EVP_MAC-Siphash(7)>,
 412 L<EVP_MAC-Poly1305(7)>
 413
 414 =head1 HISTORY
 415
 416 These functions were added in OpenSSL 3.0.
 417
 418 =head1 COPYRIGHT
 419
 420 Copyright 2018-2020 The OpenSSL Project Authors. All Rights Reserved.
 421
 422 Licensed under the Apache License 2.0 (the "License").  You may not use
 423 this file except in compliance with the License.  You can obtain a copy
 424 in the file LICENSE in the source distribution or at
 425 L<https://www.openssl.org/source/license.html>.
 426
 427 =cut