doc/man3/EVP_DigestInit.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex,
   6 EVP_MD_CTX_ctrl, EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags,
   7 EVP_MD_CTX_test_flags, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate,
   8 EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal,
   9 EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size,
  10 EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size,
  11 EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_MD_CTX_md_data,
  12 EVP_md_null,
  13 EVP_get_digestbyname, EVP_get_digestbynid,
  14 EVP_get_digestbyobj - EVP digest routines
  15
  16 =head1 SYNOPSIS
  17
  18  #include <openssl/evp.h>
  19
  20  EVP_MD_CTX *EVP_MD_CTX_new(void);
  21  int EVP_MD_CTX_reset(EVP_MD_CTX *ctx);
  22  void EVP_MD_CTX_free(EVP_MD_CTX *ctx);
  23  void EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx, int cmd, int p1, void* p2);
  24  void EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags);
  25  void EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags);
  26  int EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags);
  27
  28  int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
  29  int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
  30  int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);
  31  int EVP_DigestFinalXOF(EVP_MD_CTX *ctx, unsigned char *md, size_t len);
  32
  33  int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in);
  34
  35  int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
  36  int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);
  37
  38  int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in);
  39
  40  int EVP_MD_type(const EVP_MD *md);
  41  int EVP_MD_pkey_type(const EVP_MD *md);
  42  int EVP_MD_size(const EVP_MD *md);
  43  int EVP_MD_block_size(const EVP_MD *md);
  44
  45  const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);
  46  int EVP_MD_CTX_size(const EVP_MD *ctx);
  47  int EVP_MD_CTX_block_size(const EVP_MD *ctx);
  48  int EVP_MD_CTX_type(const EVP_MD *ctx);
  49  void *EVP_MD_CTX_md_data(const EVP_MD_CTX *ctx);
  50
  51  const EVP_MD *EVP_md_null(void);
  52
  53  const EVP_MD *EVP_get_digestbyname(const char *name);
  54  const EVP_MD *EVP_get_digestbynid(int type);
  55  const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o);
  56
  57 =head1 DESCRIPTION
  58
  59 The EVP digest routines are a high level interface to message digests,
  60 and should be used instead of the cipher-specific functions.
  61
  62 =over 4
  63
  64 =item EVP_MD_CTX_new()
  65
  66 Allocates and returns a digest context.
  67
  68 =item EVP_MD_CTX_reset()
  69
  70 Resets the digest context B<ctx>.  This can be used to reuse an already
  71 existing context.
  72
  73 =item EVP_MD_CTX_free()
  74
  75 Cleans up digest context B<ctx> and frees up the space allocated to it.
  76
  77 =item EVP_MD_CTX_ctrl()
  78
  79 Performs digest-specific control actions on context B<ctx>.
  80
  81 =item EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags(), EVP_MD_CTX_test_flags()
  82
  83 Sets, clears and tests B<ctx> flags.  See L</FLAGS> below for more information.
  84
  85 =item EVP_DigestInit_ex()
  86
  87 Sets up digest context B<ctx> to use a digest B<type> from ENGINE B<impl>.
  88 B<type> will typically be supplied by a function such as EVP_sha1().  If
  89 B<impl> is NULL then the default implementation of digest B<type> is used.
  90
  91 =item EVP_DigestUpdate()
  92
  93 Hashes B<cnt> bytes of data at B<d> into the digest context B<ctx>. This
  94 function can be called several times on the same B<ctx> to hash additional
  95 data.
  96
  97 =item EVP_DigestFinal_ex()
  98
  99 Retrieves the digest value from B<ctx> and places it in B<md>. If the B<s>
 100 parameter is not NULL then the number of bytes of data written (i.e. the
 101 length of the digest) will be written to the integer at B<s>, at most
 102 B<EVP_MAX_MD_SIZE> bytes will be written.  After calling EVP_DigestFinal_ex()
 103 no additional calls to EVP_DigestUpdate() can be made, but
 104 EVP_DigestInit_ex() can be called to initialize a new digest operation.
 105
 106 =item EVP_DigestFinalXOF()
 107
 108 Interfaces to extendable-output functions, XOFs, such as SHAKE128 and SHAKE256.
 109 It retrieves the digest value from B<ctx> and places it in B<len>-sized <B>md.
 110 After calling this function no additional calls to EVP_DigestUpdate() can be
 111 made, but EVP_DigestInit_ex() can be called to initialize a new operation.
 112
 113 =item EVP_MD_CTX_copy_ex()
 114
 115 Can be used to copy the message digest state from B<in> to B<out>. This is
 116 useful if large amounts of data are to be hashed which only differ in the last
 117 few bytes.
 118
 119 =item EVP_DigestInit()
 120
 121 Behaves in the same way as EVP_DigestInit_ex() except it always uses the
 122 default digest implementation.
 123
 124 =item EVP_DigestFinal()
 125
 126 Similar to EVP_DigestFinal_ex() except the digest context B<ctx> is
 127 automatically cleaned up.
 128
 129 =item EVP_MD_CTX_copy()
 130
 131 Similar to EVP_MD_CTX_copy_ex() except the destination B<out> does not have to
 132 be initialized.
 133
 134 =item EVP_MD_size(),
 135 EVP_MD_CTX_size()
 136
 137 Return the size of the message digest when passed an B<EVP_MD> or an
 138 B<EVP_MD_CTX> structure, i.e. the size of the hash.
 139
 140 =item EVP_MD_block_size(),
 141 EVP_MD_CTX_block_size()
 142
 143 Return the block size of the message digest when passed an B<EVP_MD> or an
 144 B<EVP_MD_CTX> structure.
 145
 146 =item EVP_MD_type(),
 147 EVP_MD_CTX_type()
 148
 149 Return the NID of the OBJECT IDENTIFIER representing the given message digest
 150 when passed an B<EVP_MD> structure.  For example, C<EVP_MD_type(EVP_sha1())>
 151 returns B<NID_sha1>. This function is normally used when setting ASN1 OIDs.
 152
 153 =item EVP_MD_CTX_md_data()
 154
 155 Return the digest method private data for the passed B<EVP_MD_CTX>.
 156 The space is allocated by OpenSSL and has the size originally set with
 157 EVP_MD_meth_set_app_datasize().
 158
 159 =item EVP_MD_CTX_md()
 160
 161 Returns the B<EVP_MD> structure corresponding to the passed B<EVP_MD_CTX>.
 162
 163 =item EVP_MD_pkey_type()
 164
 165 Returns the NID of the public key signing algorithm associated with this
 166 digest. For example EVP_sha1() is associated with RSA so this will return
 167 B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms are no
 168 longer linked this function is only retained for compatibility reasons.
 169
 170 =item EVP_md_null()
 171
 172 A "null" message digest that does nothing: i.e. the hash it returns is of zero
 173 length.
 174
 175 =item EVP_get_digestbyname(),
 176 EVP_get_digestbynid(),
 177 EVP_get_digestbyobj()
 178
 179 Returns an B<EVP_MD> structure when passed a digest name, a digest B<NID> or an
 180 B<ASN1_OBJECT> structure respectively.
 181
 182 =back
 183
 184 =head1 FLAGS
 185
 186 EVP_MD_CTX_set_flags(), EVP_MD_CTX_clear_flags() and EVP_MD_CTX_test_flags()
 187 can be used the manipulate and test these B<EVP_MD_CTX> flags:
 188
 189 =over 4
 190
 191 =item EVP_MD_CTX_FLAG_ONESHOT
 192
 193 This flag instructs the digest to optimize for one update only, if possible.
 194
 195 =for comment EVP_MD_CTX_FLAG_CLEANED is internal, don't mention it
 196
 197 =for comment EVP_MD_CTX_FLAG_REUSE is internal, don't mention it
 198
 199 =for comment We currently avoid documenting flags that are only bit holder:
 200 EVP_MD_CTX_FLAG_NON_FIPS_ALLOW, EVP_MD_CTX_FLAGS_PAD_*
 201
 202 =item EVP_MD_CTX_FLAG_NO_INIT
 203
 204 This flag instructs EVP_DigestInit() and similar not to initialise the
 205 implementation specific data.
 206
 207 =item EVP_MD_CTX_FLAG_FINALISE
 208
 209 Some functions such as EVP_DigestSign only finalise copies of internal
 210 contexts so additional data can be included after the finalisation call.
 211 This is inefficient if this functionality is not required, and can be
 212 disabled with this flag.
 213
 214 =back
 215
 216 =head1 RETURN VALUES
 217
 218 =over 4
 219
 220 =item EVP_DigestInit_ex(),
 221 EVP_DigestUpdate(),
 222 EVP_DigestFinal_ex()
 223
 224 Returns 1 for
 225 success and 0 for failure.
 226
 227 =item EVP_MD_CTX_ctrl()
 228
 229 Returns 1 if successful or 0 for failure.
 230
 231 =item EVP_MD_CTX_copy_ex()
 232
 233 Returns 1 if successful or 0 for failure.
 234
 235 =item EVP_MD_type(),
 236 EVP_MD_pkey_type(),
 237 EVP_MD_type()
 238
 239 Returns the NID of the corresponding OBJECT IDENTIFIER or NID_undef if none
 240 exists.
 241
 242 =item EVP_MD_size(),
 243 EVP_MD_block_size(),
 244 EVP_MD_CTX_size(),
 245 EVP_MD_CTX_block_size()
 246
 247 Returns the digest or block size in bytes.
 248
 249 =item EVP_md_null()
 250
 251 Returns a pointer to the B<EVP_MD> structure of the "null" message digest.
 252
 253 =item EVP_get_digestbyname(),
 254 EVP_get_digestbynid(),
 255 EVP_get_digestbyobj()
 256
 257 Returns either an B<EVP_MD> structure or NULL if an error occurs.
 258
 259 =back
 260
 261 =head1 NOTES
 262
 263 The B<EVP> interface to message digests should almost always be used in
 264 preference to the low level interfaces. This is because the code then becomes
 265 transparent to the digest used and much more flexible.
 266
 267 New applications should use the SHA-2 (such as L<EVP_sha256(3)>) or the SHA-3
 268 digest algorithms (such as L<EVP_sha3_512(3)>). The other digest algorithms
 269 are still in common use.
 270
 271 For most applications the B<impl> parameter to EVP_DigestInit_ex() will be
 272 set to NULL to use the default digest implementation.
 273
 274 The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are
 275 obsolete but are retained to maintain compatibility with existing code. New
 276 applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and
 277 EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context
 278 instead of initializing and cleaning it up on each call and allow non default
 279 implementations of digests to be specified.
 280
 281 If digest contexts are not cleaned up after use
 282 memory leaks will occur.
 283
 284 EVP_MD_CTX_size(), EVP_MD_CTX_block_size(), EVP_MD_CTX_type(),
 285 EVP_get_digestbynid() and EVP_get_digestbyobj() are defined as
 286 macros.
 287
 288 EVP_MD_CTX_ctrl() sends commands to message digests for additional configuration
 289 or control.
 290
 291 =head1 EXAMPLE
 292
 293 This example digests the data "Test Message\n" and "Hello World\n", using the
 294 digest name passed on the command line.
 295
 296  #include <stdio.h>
 297  #include <openssl/evp.h>
 298
 299  main(int argc, char *argv[])
 300  {
 301      EVP_MD_CTX *mdctx;
 302      const EVP_MD *md;
 303      char mess1[] = "Test Message\n";
 304      char mess2[] = "Hello World\n";
 305      unsigned char md_value[EVP_MAX_MD_SIZE];
 306      int md_len, i;
 307
 308      if (argv[1] == NULL) {
 309          printf("Usage: mdtest digestname\n");
 310          exit(1);
 311      }
 312
 313      md = EVP_get_digestbyname(argv[1]);
 314      if (md == NULL) {
 315          printf("Unknown message digest %s\n", argv[1]);
 316          exit(1);
 317      }
 318
 319      mdctx = EVP_MD_CTX_new();
 320      EVP_DigestInit_ex(mdctx, md, NULL);
 321      EVP_DigestUpdate(mdctx, mess1, strlen(mess1));
 322      EVP_DigestUpdate(mdctx, mess2, strlen(mess2));
 323      EVP_DigestFinal_ex(mdctx, md_value, &md_len);
 324      EVP_MD_CTX_free(mdctx);
 325
 326      printf("Digest is: ");
 327      for (i = 0; i < md_len; i++)
 328          printf("%02x", md_value[i]);
 329      printf("\n");
 330
 331      exit(0);
 332  }
 333
 334 =head1 SEE ALSO
 335
 336 L<dgst(1)>,
 337 L<evp(7)>
 338
 339 The full list of digest algorithms are provided below.
 340
 341 L<EVP_blake2b512(3)>,
 342 L<EVP_md2(3)>,
 343 L<EVP_md4(3)>,
 344 L<EVP_md5(3)>,
 345 L<EVP_mdc2(3)>,
 346 L<EVP_ripemd160(3)>,
 347 L<EVP_sha1(3)>,
 348 L<EVP_sha224(3)>,
 349 L<EVP_sha3_224(3)>,
 350 L<EVP_sm3(3)>,
 351 L<EVP_whirlpool(3)>
 352
 353 =head1 HISTORY
 354
 355 EVP_MD_CTX_create() and EVP_MD_CTX_destroy() were renamed to
 356 EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1.0.
 357
 358 The link between digests and signing algorithms was fixed in OpenSSL 1.0 and
 359 later, so now EVP_sha1() can be used with RSA and DSA.
 360
 361 EVP_dss1() was removed in OpenSSL 1.1.0.
 362
 363 =head1 COPYRIGHT
 364
 365 Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
 366
 367 Licensed under the OpenSSL license (the "License").  You may not use
 368 this file except in compliance with the License.  You can obtain a copy
 369 in the file LICENSE in the source distribution or at
 370 L<https://www.openssl.org/source/license.html>.
 371
 372 =cut