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