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_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_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_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 "flags" (B<OSSL_MAC_PARAM_FLAGS>) <integer>
 229
 230 These will set the MAC flags to the given numbers.
 231 Some MACs do not support this option.
 232
 233 =item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string>
 234
 235 =item "digest" (B<OSSL_MAC_PARAM_DIGEST>) <UTF8 string>
 236
 237 =item "cipher" (B<OSSL_MAC_PARAM_CIPHER>) <UTF8 string>
 238
 239 For MAC implementations that use an underlying computation cipher or
 240 digest, these parameters set what the algorithm should be.
 241
 242 The value is always the name of the intended algorithm,
 243 or the properties.
 244
 245 Note that not all algorithms may support all digests.
 246 HMAC does not support variable output length digests such as SHAKE128
 247 or SHAKE256.
 248
 249 =item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
 250
 251 For MAC implementations that support it, set the output size that
 252 EVP_MAC_final() should produce.
 253 The allowed sizes vary between MAC implementations, but must never exceed
 254 what can be given with a B<size_t>.
 255
 256 =item "tls-data-size" (B<OSSL_MAC_PARAM_TLS_DATA_SIZE>) <unsigned integer>
 257
 258 This parameter is only supported by HMAC. If set then special handling is
 259 activated for calculating the MAC of a received mac-then-encrypt TLS record
 260 where variable length record padding has been used (as in the case of CBC mode
 261 ciphersuites). The value represents the total length of the record that is
 262 having the MAC calculated including the received MAC and the record padding.
 263
 264 When used EVP_MAC_update must be called precisely twice. The first time with
 265 the 13 bytes of TLS "header" data, and the second time with the entire record
 266 including the MAC itself and any padding. The entire record length must equal
 267 the value passed in the "tls-data-size" parameter. The length passed in the
 268 B<datalen> parameter to EVP_MAC_update() should be equal to the length of the
 269 record after the MAC and any padding has been removed.
 270
 271 =back
 272
 273 All these parameters should be used before the calls to any of
 274 EVP_MAC_init(), EVP_MAC_update() and EVP_MAC_final() for a full
 275 computation.
 276 Anything else may give undefined results.
 277
 278 =head1 RETURN VALUES
 279
 280 EVP_MAC_fetch() returns a pointer to a newly fetched EVP_MAC, or
 281 NULL if allocation failed.
 282
 283 EVP_MAC_up_ref() returns 1 on success, 0 on error.
 284
 285 EVP_MAC_free() returns nothing at all.
 286
 287 EVP_MAC_is_a() returns 1 if the given method can be identified with
 288 the given name, otherwise 0.
 289
 290 EVP_MAC_name() returns a name of the MAC, or NULL on error.
 291
 292 EVP_MAC_provider() returns a pointer to the provider for the MAC, or
 293 NULL on error.
 294
 295 EVP_MAC_CTX_new() and EVP_MAC_CTX_dup() return a pointer to a newly
 296 created EVP_MAC_CTX, or NULL if allocation failed.
 297
 298 EVP_MAC_CTX_free() returns nothing at all.
 299
 300 EVP_MAC_CTX_get_params() and EVP_MAC_CTX_set_params() return 1 on
 301 success, 0 on error.
 302
 303 EVP_MAC_init(), EVP_MAC_update(), and EVP_MAC_final() return 1 on success, 0
 304 on error.
 305
 306 EVP_MAC_size() returns the expected output size, or 0 if it isn't
 307 set.
 308 If it isn't set, a call to EVP_MAC_init() should get it set.
 309
 310 EVP_MAC_do_all_provided() returns nothing at all.
 311
 312 =head1 EXAMPLES
 313
 314   #include <stdlib.h>
 315   #include <stdio.h>
 316   #include <string.h>
 317   #include <stdarg.h>
 318   #include <unistd.h>
 319
 320   #include <openssl/evp.h>
 321   #include <openssl/err.h>
 322   #include <openssl/params.h>
 323
 324   int main() {
 325       EVP_MAC *mac = EVP_MAC_fetch(NULL, getenv("MY_MAC"), NULL);
 326       const char *cipher = getenv("MY_MAC_CIPHER");
 327       const char *digest = getenv("MY_MAC_DIGEST");
 328       const char *key = getenv("MY_KEY");
 329       EVP_MAC_CTX *ctx = NULL;
 330
 331       unsigned char buf[4096];
 332       size_t read_l;
 333       size_t final_l;
 334
 335       size_t i;
 336
 337       OSSL_PARAM params[4];
 338       size_t params_n = 0;
 339
 340       if (cipher != NULL)
 341           params[params_n++] =
 342               OSSL_PARAM_construct_utf8_string("cipher", (char*)cipher, 0);
 343       if (digest != NULL)
 344           params[params_n++] =
 345               OSSL_PARAM_construct_utf8_string("digest", (char*)digest, 0);
 346       params[params_n++] =
 347           OSSL_PARAM_construct_octet_string("key", (void*)key, strlen(key));
 348       params[params_n] = OSSL_PARAM_construct_end();
 349
 350       if (mac == NULL
 351           || key == NULL
 352           || (ctx = EVP_MAC_CTX_new(mac)) == NULL
 353           || EVP_MAC_CTX_set_params(ctx, params) <= 0)
 354           goto err;
 355
 356       if (!EVP_MAC_init(ctx))
 357           goto err;
 358
 359       while ( (read_l = read(STDIN_FILENO, buf, sizeof(buf))) > 0) {
 360           if (!EVP_MAC_update(ctx, buf, read_l))
 361               goto err;
 362       }
 363
 364       if (!EVP_MAC_final(ctx, buf, &final_l, sizeof(buf)))
 365           goto err;
 366
 367       printf("Result: ");
 368       for (i = 0; i < final_l; i++)
 369           printf("%02X", buf[i]);
 370       printf("\n");
 371
 372       EVP_MAC_CTX_free(ctx);
 373       EVP_MAC_free(mac);
 374       exit(0);
 375
 376    err:
 377       EVP_MAC_CTX_free(ctx);
 378       EVP_MAC_free(mac);
 379       fprintf(stderr, "Something went wrong\n");
 380       ERR_print_errors_fp(stderr);
 381       exit (1);
 382   }
 383
 384 A run of this program, called with correct environment variables, can
 385 look like this:
 386
 387   $ MY_MAC=cmac MY_KEY=secret0123456789 MY_MAC_CIPHER=aes-128-cbc \
 388     LD_LIBRARY_PATH=. ./foo < foo.c
 389   Result: C5C06683CD9DDEF904D754505C560A4E
 390
 391 (in this example, that program was stored in F<foo.c> and compiled to
 392 F<./foo>)
 393
 394 =head1 SEE ALSO
 395
 396 L<property(7)>
 397 L<OSSL_PARAM(3)>,
 398 L<EVP_MAC-BLAKE2(7)>,
 399 L<EVP_MAC-CMAC(7)>,
 400 L<EVP_MAC-GMAC(7)>,
 401 L<EVP_MAC-HMAC(7)>,
 402 L<EVP_MAC-KMAC(7)>,
 403 L<EVP_MAC-Siphash(7)>,
 404 L<EVP_MAC-Poly1305(7)>
 405
 406 =head1 HISTORY
 407
 408 These functions were added in OpenSSL 3.0.
 409
 410 =head1 COPYRIGHT
 411
 412 Copyright 2018-2020 The OpenSSL Project Authors. All Rights Reserved.
 413
 414 Licensed under the Apache License 2.0 (the "License").  You may not use
 415 this file except in compliance with the License.  You can obtain a copy
 416 in the file LICENSE in the source distribution or at
 417 L<https://www.openssl.org/source/license.html>.
 418
 419 =cut