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_reset() resets the computation for the given context.
  91 This may not be supported by the MAC implementation.
  92
  93 EVP_MAC_update() adds C<datalen> bytes from C<data> to the MAC input.
  94
  95 EVP_MAC_final() does the final computation and stores the result in
  96 the memory pointed at by C<out>, and sets its size in the B<size_t>
  97 the C<poutlen> points at.
  98 If C<out> is B<NULL>, then no computation is made.
  99 To figure out what the output length will be and allocate space for it
 100 dynamically, simply call with C<out> being B<NULL> and C<poutlen>
 101 pointing at a valid location, then allocate space and make a second
 102 call with C<out> pointing at the allocated space.
 103
 104 EVP_MAC_ctrl() is used to manipulate or get information on aspects of
 105 the MAC which may vary depending on the MAC algorithm or its
 106 implementation.
 107 This includes the MAC key, and for MACs that use other algorithms to
 108 do their computation, this is also the way to tell it which one to
 109 use.
 110 This functions takes variable arguments, the exact expected arguments
 111 depend on C<cmd>.
 112 EVP_MAC_ctrl() can be called both before and after EVP_MAC_init(), but
 113 the effect will depend on what control is being use.
 114 See </CONTROLS> below for a description of standard controls.
 115
 116 EVP_MAC_vctrl() is the variant of EVP_MAC_ctrl() that takes a
 117 C<va_list> argument instead of variadic arguments.
 118
 119 EVP_MAC_ctrl_str() is an alternative to EVP_MAC_ctrl() to control the
 120 MAC implementation as E<lt> C<type>, C<value> E<gt> pairs.
 121 The MAC implementation documentation should specify what control type
 122 strings are accepted.
 123
 124 EVP_MAC_str2ctrl() and EVP_MAC_hex2ctrl() are helper functions to
 125 control the MAC implementation with raw strings or with strings
 126 containing hexadecimal numbers.
 127 The latter are decoded into bitstrings that are sent on to
 128 EVP_MAC_ctrl().
 129
 130 =head2 Information functions
 131
 132 EVP_MAC_size() returns the MAC output size for the given context.
 133
 134 EVP_MAC_nid() returns the numeric identity of the given MAC implementation.
 135
 136 EVP_MAC_name() returns the name of the given MAC implementation.
 137
 138 =head2 Object database functions
 139
 140 EVP_get_macbyname() fetches a MAC implementation from the object
 141 database by name.
 142
 143 EVP_get_macbynid() fetches a MAC implementation from the object
 144 database by numeric identity.
 145
 146 EVP_get_macbyobj() fetches a MAC implementation from the object
 147 database by ASN.1 OBJECT (i.e. an encoded OID).
 148
 149 =head1 CONTROLS
 150
 151 The standard controls are:
 152
 153 =over 4
 154
 155 =item B<EVP_MAC_CTRL_SET_KEY>
 156
 157 This control expects two arguments: C<unsigned char *key>, C<size_t keylen>
 158
 159 These will set the MAC key from the given string of the given length.
 160 The string may be any bitstring, and can contain NUL bytes.
 161
 162 For MACs that use an underlying computation algorithm, the algorithm
 163 I<must> be set first, see B<EVP_MAC_CTRL_SET_ENGINE>,
 164 B<EVP_MAC_CTRL_SET_MD> and B<EVP_MAC_CTRL_SET_CIPHER> below.
 165
 166 =item B<EVP_MAC_CTRL_SET_IV>
 167
 168 This control expects two arguments: C<unsigned char *key>, C<size_t keylen>
 169
 170 Some MAC implementations require an IV, this control sets the IV.
 171
 172 =item B<EVP_MAC_CTRL_SET_FLAGS>
 173
 174 This control expects one arguments: C<unsigned long flags>
 175
 176 These will set the MAC flags to the given numbers.
 177 Some MACs do not support this option.
 178
 179 =item B<EVP_MAC_CTRL_SET_ENGINE>
 180
 181 =item B<EVP_MAC_CTRL_SET_MD>
 182
 183 =item B<EVP_MAC_CTRL_SET_CIPHER>
 184
 185 For MAC implementations that use an underlying computation algorithm,
 186 these controls set what the algorithm should be, and the engine that
 187 implements the algorithm if needed.
 188
 189 B<EVP_MAC_CTRL_SET_ENGINE> takes one argument: C<ENGINE *>
 190
 191 B<EVP_MAC_CTRL_SET_MD> takes one argument: C<EVP_MD *>
 192
 193 B<EVP_MAC_CTRL_SET_CIPHER> takes one argument: C<EVP_CIPHER *>
 194
 195 =item B<EVP_MAC_CTRL_SET_SIZE>
 196
 197 For MAC implementations that support it, set the output size that
 198 EVP_MAC_final() should produce.
 199 The allowed sizes vary between MAC implementations.
 200
 201 =back
 202
 203 All these control should be used before the calls to any of
 204 EVP_MAC_init(), EVP_MAC_update() and EVP_MAC_final() for a full
 205 computation.
 206 Anything else may give undefined results.
 207
 208 =head1 NOTES
 209
 210 EVP_get_macbynid(), EVP_get_macbyobj() and EVP_MAC_name() are
 211 implemented as a macro.
 212
 213 =head1 RETURN VALUES
 214
 215 EVP_MAC_CTX_new() and EVP_MAC_CTX_new_id() return a pointer to a newly
 216 created EVP_MAC_CTX, or NULL if allocation failed.
 217
 218 EVP_MAC_CTX_free() returns nothing at all.
 219
 220 EVP_MAC_CTX_copy(), EVP_MAC_reset(), EVP_MAC_init(), EVP_MAC_update(),
 221 and EVP_MAC_final() return 1 on success, 0 on error.
 222
 223 EVP_MAC_ctrl(), EVP_MAC_ctrl_str(), EVP_MAC_str2ctrl() and
 224 EVP_MAC_hex2ctrl() return 1 on success and 0 or a negative value on
 225 error.
 226 In particular, the value -2 indicates that the given control type
 227 isn't supported by the MAC implementation.
 228
 229 EVP_MAC_size() returns the expected output size, or 0 if it isn't
 230 set.
 231 If it isn't set, a call to EVP_MAC_init() should get it set.
 232
 233 EVP_MAC_nid() returns the numeric identity for the given C<mac>.
 234
 235 EVP_MAC_name() returns the name for the given C<mac>, if it has been
 236 added to the object database.
 237
 238 EVP_add_mac() returns 1 if the given C<mac> was successfully added to
 239 the object database, otherwise 0.
 240
 241 EVP_get_macbyname(), EVP_get_macbynid() and EVP_get_macbyobj() return
 242 the request MAC implementation, if it exists in the object database,
 243 otherwise B<NULL>.
 244
 245 =head1 EXAMPLE
 246
 247   #include <stdlib.h>
 248   #include <stdio.h>
 249   #include <string.h>
 250   #include <stdarg.h>
 251   #include <unistd.h>
 252
 253   #include <openssl/evp.h>
 254   #include <openssl/err.h>
 255
 256   int ctrl_ign_unsupported(EVP_MAC_CTX *ctx, int cmd, ...)
 257   {
 258       va_list args;
 259       int rv;
 260
 261       va_start(args, cmd);
 262       rv = EVP_MAC_vctrl(ctx, cmd, args);
 263       va_end(args);
 264
 265       if (rv == -2)
 266           rv = 1;       /* Ignore unsupported, pretend it worked fine */
 267
 268       return rv;
 269   }
 270
 271   int main() {
 272       const EVP_MAC *mac =
 273           EVP_get_macbyname(getenv("MY_MAC"));
 274       const EVP_CIPHER *cipher =
 275           EVP_get_cipherbyname(getenv("MY_MAC_CIPHER"));
 276       const EVP_MD *digest =
 277           EVP_get_digestbyname(getenv("MY_MAC_DIGEST"));
 278       const char *key = getenv("MY_KEY");
 279       EVP_MAC_CTX *ctx = NULL;
 280
 281       unsigned char buf[4096];
 282       ssize_t read_l;
 283       size_t final_l;
 284
 285       size_t i;
 286
 287       if (mac == NULL
 288           || key == NULL
 289           || (ctx = EVP_MAC_CTX_new(mac)) == NULL
 290           || (cipher != NULL
 291               && !ctrl_ign_unsupported(ctx, EVP_MAC_CTRL_SET_CIPHER, cipher))
 292           || (digest != NULL
 293               && !ctrl_ign_unsupported(ctx, EVP_MAC_CTRL_SET_MD, digest))
 294           || EVP_MAC_ctrl(ctx, EVP_MAC_CTRL_SET_KEY, key, strlen(key)) <= 0)
 295           goto err;
 296
 297       if (!EVP_MAC_init(ctx))
 298           goto err;
 299
 300       while ( (read_l = read(STDIN_FILENO, buf, sizeof(buf))) < 0) {
 301           if (!EVP_MAC_update(ctx, buf, read_l))
 302               goto err;
 303       }
 304
 305       if (!EVP_MAC_final(ctx, buf, &final_l))
 306           goto err;
 307
 308       printf("Result: ");
 309       for (i = 0; i < final_l; i++)
 310           printf("%02X", buf[i]);
 311       printf("\n");
 312
 313       EVP_MAC_CTX_free(ctx);
 314       exit(0);
 315
 316    err:
 317       EVP_MAC_CTX_free(ctx);
 318       fprintf(stderr, "Something went wrong\n");
 319       ERR_print_errors_fp(stderr);
 320       exit (1);
 321   }
 322
 323 A run of this program, called with correct environment variables, can
 324 look like this:
 325
 326   $ MY_MAC=cmac MY_KEY=secret0123456789 MY_MAC_CIPHER=aes-128-cbc \
 327     LD_LIBRARY_PATH=. ./foo < foo.c
 328   Result: ECCAAFF041B22A2299EB90A1B53B6D45
 329
 330 (in this example, that program was stored in F<foo.c> and compiled to
 331 F<./foo>)
 332
 333 =head1 SEE ALSO
 334
 335 L<EVP_MAC_CMAC(7)>,
 336 L<EVP_MAC_GMAC(7)>,
 337 L<EVP_MAC_HMAC(7)>,
 338 L<EVP_MAC_SIPHASH(7)>,
 339 L<EVP_MAC_POLY1305(7)>
 340
 341 =head1 COPYRIGHT
 342
 343 Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
 344
 345 Licensed under the OpenSSL license (the "License").  You may not use
 346 this file except in compliance with the License.  You can obtain a copy
 347 in the file LICENSE in the source distribution or at
 348 L<https://www.openssl.org/source/license.html>.
 349
 350 =cut