doc/man3/EVP_MAC.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_MAC, EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_new_id, EVP_MAC_CTX_free,
   6 EVP_MAC_CTX_copy, EVP_MAC_CTX_mac, EVP_MAC_size, EVP_MAC_init, EVP_MAC_update,
   7 EVP_MAC_final, EVP_MAC_ctrl, EVP_MAC_vctrl, EVP_MAC_ctrl_str,
   8 EVP_MAC_str2ctrl, EVP_MAC_hex2ctrl, EVP_MAC_nid, EVP_MAC_name,
   9 EVP_get_macbyname, EVP_get_macbynid, EVP_get_macbyobj - EVP MAC routines
  10
  11 =head1 SYNOPSIS
  12
  13  #include <openssl/evp.h>
  14
  15  typedef struct evp_mac_st EVP_MAC;
  16  typedef struct evp_mac_ctx_st EVP_MAC_CTX;
  17
  18  EVP_MAC_CTX *EVP_MAC_CTX_new(const EVP_MAC *mac);
  19  EVP_MAC_CTX *EVP_MAC_CTX_new_id(int nid);
  20  void EVP_MAC_CTX_free(EVP_MAC_CTX *ctx);
  21  int EVP_MAC_CTX_copy(EVP_MAC_CTX *dest, EVP_MAC_CTX *src);
  22  const EVP_MAC *EVP_MAC_CTX_mac(EVP_MAC_CTX *ctx);
  23  size_t EVP_MAC_size(EVP_MAC_CTX *ctx);
  24  int EVP_MAC_init(EVP_MAC_CTX *ctx);
  25  int EVP_MAC_update(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
  26  int EVP_MAC_final(EVP_MAC_CTX *ctx, unsigned char *out, size_t *poutlen);
  27  int EVP_MAC_ctrl(EVP_MAC_CTX *ctx, int cmd, ...);
  28  int EVP_MAC_vctrl(EVP_MAC_CTX *ctx, int cmd, va_list args);
  29  int EVP_MAC_ctrl_str(EVP_MAC_CTX *ctx, const char *type, const char *value);
  30  int EVP_MAC_str2ctrl(EVP_MAC_CTX *ctx, int cmd, const char *value);
  31  int EVP_MAC_hex2ctrl(EVP_MAC_CTX *ctx, int cmd, const char *value);
  32  int EVP_MAC_nid(const EVP_MAC *mac);
  33  const char *EVP_MAC_name(const EVP_MAC *mac);
  34  const EVP_MAC *EVP_get_macbyname(const char *name);
  35  const EVP_MAC *EVP_get_macbynid(int nid);
  36  const EVP_MAC *EVP_get_macbyobj(const ASN1_OBJECT *o);
  37
  38 =head1 DESCRIPTION
  39
  40 These types and functions help the application to calculate MACs of
  41 different types and with different underlying algorithms if there are
  42 any.
  43
  44 MACs are a bit complex insofar that some of them use other algorithms
  45 for actual computation.  HMAC uses a digest, and CMAC uses a cipher.
  46 Therefore, there are sometimes two contexts to keep track of, one for
  47 the MAC algorithm itself and one for the underlying computation
  48 algorithm if there is one.
  49
  50 To make things less ambiguous, this manual talks about a "context" or
  51 "MAC context", which is to denote the MAC level context, and about a
  52 "underlying context", or "computation context", which is to denote the
  53 context for the underlying computation algorithm if there is one.
  54
  55 =head2 Types
  56
  57 B<EVP_MAC> is a type that holds the implementation of a MAC.
  58
  59 B<EVP_MAC_CTX> is a context type that holds internal MAC information
  60 as well as a reference to a computation context, for those MACs that
  61 rely on an underlying computation algorithm.
  62
  63 =head2 Context manipulation functions
  64
  65 EVP_MAC_CTX_new() creates a new context for the MAC type C<mac>.
  66 EVP_MAC_CTX_new_id() creates a new context for the numerical MAC
  67 identity <nid>.
  68 The created context can then be used with most other functions
  69 described here.
  70
  71 EVP_MAC_CTX_free() frees the contents of the context, including an
  72 underlying context if there is one, as well as the context itself.
  73 B<NULL> is a valid parameter, for which this function is a no-op.
  74
  75 EVP_MAC_CTX_copy() makes a deep copy of the C<src> context to the
  76 C<dest> context.
  77 The C<dest> context I<must> have been created before calling this
  78 function.
  79
  80 EVP_MAC_CTX_mac() returns the B<EVP_MAC> associated with the context
  81 C<ctx>.
  82
  83 =head2 Computing functions
  84
  85 EVP_MAC_init() sets up the underlying context with information given
  86 through diverse controls.
  87 This should be called before calling EVP_MAC_update() and
  88 EVP_MAC_final().
  89
  90 EVP_MAC_update() adds C<datalen> bytes from C<data> to the MAC input.
  91
  92 EVP_MAC_final() does the final computation and stores the result in
  93 the memory pointed at by C<out>, and sets its size in the B<size_t>
  94 the C<poutlen> points at.
  95 If C<out> is B<NULL>, then no computation is made.
  96 To figure out what the output length will be and allocate space for it
  97 dynamically, simply call with C<out> being B<NULL> and C<poutlen>
  98 pointing at a valid location, then allocate space and make a second
  99 call with C<out> pointing at the allocated space.
 100
 101 EVP_MAC_ctrl() is used to manipulate or get information on aspects of
 102 the MAC which may vary depending on the MAC algorithm or its
 103 implementation.
 104 This includes the MAC key, and for MACs that use other algorithms to
 105 do their computation, this is also the way to tell it which one to
 106 use.
 107 This functions takes variable arguments, the exact expected arguments
 108 depend on C<cmd>.
 109 EVP_MAC_ctrl() can be called both before and after EVP_MAC_init(), but
 110 the effect will depend on what control is being use.
 111 See L</CONTROLS> below for a description of standard controls.
 112
 113 EVP_MAC_vctrl() is the variant of EVP_MAC_ctrl() that takes a
 114 C<va_list> argument instead of variadic arguments.
 115
 116 EVP_MAC_ctrl_str() is an alternative to EVP_MAC_ctrl() to control the
 117 MAC implementation as E<lt> C<type>, C<value> E<gt> pairs.
 118 The MAC implementation documentation should specify what control type
 119 strings are accepted.
 120
 121 EVP_MAC_str2ctrl() and EVP_MAC_hex2ctrl() are helper functions to
 122 control the MAC implementation with raw strings or with strings
 123 containing hexadecimal numbers.
 124 The latter are decoded into bitstrings that are sent on to
 125 EVP_MAC_ctrl().
 126
 127 =head2 Information functions
 128
 129 EVP_MAC_size() returns the MAC output size for the given context.
 130
 131 EVP_MAC_nid() returns the numeric identity of the given MAC implementation.
 132
 133 EVP_MAC_name() returns the name of the given MAC implementation.
 134
 135 =head2 Object database functions
 136
 137 EVP_get_macbyname() fetches a MAC implementation from the object
 138 database by name.
 139
 140 EVP_get_macbynid() fetches a MAC implementation from the object
 141 database by numeric identity.
 142
 143 EVP_get_macbyobj() fetches a MAC implementation from the object
 144 database by ASN.1 OBJECT (i.e. an encoded OID).
 145
 146 =head1 CONTROLS
 147
 148 The standard controls are:
 149
 150 =over 4
 151
 152 =item B<EVP_MAC_CTRL_SET_KEY>
 153
 154 This control expects two arguments: C<unsigned char *key>, C<size_t keylen>
 155
 156 These will set the MAC key from the given string of the given length.
 157 The string may be any bitstring, and can contain NUL bytes.
 158
 159 For MACs that use an underlying computation algorithm, the algorithm
 160 I<must> be set first, see B<EVP_MAC_CTRL_SET_ENGINE>,
 161 B<EVP_MAC_CTRL_SET_MD> and B<EVP_MAC_CTRL_SET_CIPHER> below.
 162
 163 =item B<EVP_MAC_CTRL_SET_IV>
 164
 165 This control expects two arguments: C<unsigned char *key>, C<size_t keylen>
 166
 167 Some MAC implementations require an IV, this control sets the IV.
 168
 169 =item B<EVP_MAC_CTRL_SET_CUSTOM>
 170
 171 This control expects two arguments: C<unsigned char *custom>, C<size_t customlen>
 172
 173 Some MAC implementations (KMAC, BLAKE2) accept a Customization String,
 174 this control sets the Customization String. The default value is "".
 175
 176 =item B<EVP_MAC_CTRL_SET_SALT>
 177
 178 This control expects two arguments: C<unsigned char *salt>, C<size_t saltlen>
 179
 180 This option is used by BLAKE2 MAC.
 181
 182 =item B<EVP_MAC_CTRL_SET_XOF>
 183
 184 This control expects one argument: C<int xof>
 185
 186 This option is used by KMAC.
 187
 188 =item B<EVP_MAC_CTRL_SET_FLAGS>
 189
 190 This control expects one argument: C<unsigned long flags>
 191
 192 These will set the MAC flags to the given numbers.
 193 Some MACs do not support this option.
 194
 195 =item B<EVP_MAC_CTRL_SET_ENGINE>
 196
 197 =item B<EVP_MAC_CTRL_SET_MD>
 198
 199 =item B<EVP_MAC_CTRL_SET_CIPHER>
 200
 201 For MAC implementations that use an underlying computation algorithm,
 202 these controls set what the algorithm should be, and the engine that
 203 implements the algorithm if needed.
 204
 205 B<EVP_MAC_CTRL_SET_ENGINE> takes one argument: C<ENGINE *>
 206
 207 B<EVP_MAC_CTRL_SET_MD> takes one argument: C<EVP_MD *>
 208
 209 B<EVP_MAC_CTRL_SET_CIPHER> takes one argument: C<EVP_CIPHER *>
 210
 211 =item B<EVP_MAC_CTRL_SET_SIZE>
 212
 213 For MAC implementations that support it, set the output size that
 214 EVP_MAC_final() should produce.
 215 The allowed sizes vary between MAC implementations.
 216
 217 =back
 218
 219 All these control should be used before the calls to any of
 220 EVP_MAC_init(), EVP_MAC_update() and EVP_MAC_final() for a full
 221 computation.
 222 Anything else may give undefined results.
 223
 224 =head1 NOTES
 225
 226 EVP_get_macbynid(), EVP_get_macbyobj() and EVP_MAC_name() are
 227 implemented as a macro.
 228
 229 =head1 RETURN VALUES
 230
 231 EVP_MAC_CTX_new() and EVP_MAC_CTX_new_id() return a pointer to a newly
 232 created EVP_MAC_CTX, or NULL if allocation failed.
 233
 234 EVP_MAC_CTX_free() returns nothing at all.
 235
 236 EVP_MAC_CTX_copy(), EVP_MAC_init(), EVP_MAC_update(),
 237 and EVP_MAC_final() return 1 on success, 0 on error.
 238
 239 EVP_MAC_ctrl(), EVP_MAC_ctrl_str(), EVP_MAC_str2ctrl() and
 240 EVP_MAC_hex2ctrl() return 1 on success and 0 or a negative value on
 241 error.
 242 In particular, the value -2 indicates that the given control type
 243 isn't supported by the MAC implementation.
 244
 245 EVP_MAC_size() returns the expected output size, or 0 if it isn't
 246 set.
 247 If it isn't set, a call to EVP_MAC_init() should get it set.
 248
 249 EVP_MAC_nid() returns the numeric identity for the given C<mac>.
 250
 251 EVP_MAC_name() returns the name for the given C<mac>, if it has been
 252 added to the object database.
 253
 254 EVP_add_mac() returns 1 if the given C<mac> was successfully added to
 255 the object database, otherwise 0.
 256
 257 EVP_get_macbyname(), EVP_get_macbynid() and EVP_get_macbyobj() return
 258 the request MAC implementation, if it exists in the object database,
 259 otherwise B<NULL>.
 260
 261 =head1 EXAMPLE
 262
 263   #include <stdlib.h>
 264   #include <stdio.h>
 265   #include <string.h>
 266   #include <stdarg.h>
 267   #include <unistd.h>
 268
 269   #include <openssl/evp.h>
 270   #include <openssl/err.h>
 271
 272   int ctrl_ign_unsupported(EVP_MAC_CTX *ctx, int cmd, ...)
 273   {
 274       va_list args;
 275       int rv;
 276
 277       va_start(args, cmd);
 278       rv = EVP_MAC_vctrl(ctx, cmd, args);
 279       va_end(args);
 280
 281       if (rv == -2)
 282           rv = 1;       /* Ignore unsupported, pretend it worked fine */
 283
 284       return rv;
 285   }
 286
 287   int main() {
 288       const EVP_MAC *mac =
 289           EVP_get_macbyname(getenv("MY_MAC"));
 290       const EVP_CIPHER *cipher =
 291           EVP_get_cipherbyname(getenv("MY_MAC_CIPHER"));
 292       const EVP_MD *digest =
 293           EVP_get_digestbyname(getenv("MY_MAC_DIGEST"));
 294       const char *key = getenv("MY_KEY");
 295       EVP_MAC_CTX *ctx = NULL;
 296
 297       unsigned char buf[4096];
 298       ssize_t read_l;
 299       size_t final_l;
 300
 301       size_t i;
 302
 303       if (mac == NULL
 304           || key == NULL
 305           || (ctx = EVP_MAC_CTX_new(mac)) == NULL
 306           || (cipher != NULL
 307               && !ctrl_ign_unsupported(ctx, EVP_MAC_CTRL_SET_CIPHER, cipher))
 308           || (digest != NULL
 309               && !ctrl_ign_unsupported(ctx, EVP_MAC_CTRL_SET_MD, digest))
 310           || EVP_MAC_ctrl(ctx, EVP_MAC_CTRL_SET_KEY, key, strlen(key)) <= 0)
 311           goto err;
 312
 313       if (!EVP_MAC_init(ctx))
 314           goto err;
 315
 316       while ( (read_l = read(STDIN_FILENO, buf, sizeof(buf))) < 0) {
 317           if (!EVP_MAC_update(ctx, buf, read_l))
 318               goto err;
 319       }
 320
 321       if (!EVP_MAC_final(ctx, buf, &final_l))
 322           goto err;
 323
 324       printf("Result: ");
 325       for (i = 0; i < final_l; i++)
 326           printf("%02X", buf[i]);
 327       printf("\n");
 328
 329       EVP_MAC_CTX_free(ctx);
 330       exit(0);
 331
 332    err:
 333       EVP_MAC_CTX_free(ctx);
 334       fprintf(stderr, "Something went wrong\n");
 335       ERR_print_errors_fp(stderr);
 336       exit (1);
 337   }
 338
 339 A run of this program, called with correct environment variables, can
 340 look like this:
 341
 342   $ MY_MAC=cmac MY_KEY=secret0123456789 MY_MAC_CIPHER=aes-128-cbc \
 343     LD_LIBRARY_PATH=. ./foo < foo.c
 344   Result: ECCAAFF041B22A2299EB90A1B53B6D45
 345
 346 (in this example, that program was stored in F<foo.c> and compiled to
 347 F<./foo>)
 348
 349 =head1 SEE ALSO
 350
 351 L<EVP_MAC_BLAKE2(7)>,
 352 L<EVP_MAC_CMAC(7)>,
 353 L<EVP_MAC_GMAC(7)>,
 354 L<EVP_MAC_HMAC(7)>,
 355 L<EVP_MAC_KMAC(7)>,
 356 L<EVP_MAC_SIPHASH(7)>,
 357 L<EVP_MAC_POLY1305(7)>
 358
 359 =head1 COPYRIGHT
 360
 361 Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
 362
 363 Licensed under the Apache License 2.0 (the "License").  You may not use
 364 this file except in compliance with the License.  You can obtain a copy
 365 in the file LICENSE in the source distribution or at
 366 L<https://www.openssl.org/source/license.html>.
 367
 368 =cut