1=pod 2 3=head1 NAME 4 5EVP_VerifyInit_ex, 6EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal_ex, EVP_VerifyFinal 7- EVP signature verification functions 8 9=head1 SYNOPSIS 10 11 #include <openssl/evp.h> 12 13 int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); 14 int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); 15 int EVP_VerifyFinal_ex(EVP_MD_CTX *ctx, const unsigned char *sigbuf, 16 unsigned int siglen, EVP_PKEY *pkey, 17 OSSL_LIB_CTX *libctx, const char *propq); 18 int EVP_VerifyFinal(EVP_MD_CTX *ctx, unsigned char *sigbuf, unsigned int siglen, 19 EVP_PKEY *pkey); 20 21 int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); 22 23=head1 DESCRIPTION 24 25The EVP signature verification routines are a high-level interface to digital 26signatures. 27 28EVP_VerifyInit_ex() sets up verification context I<ctx> to use digest 29I<type> from ENGINE I<impl>. I<ctx> must be created by calling 30EVP_MD_CTX_new() before calling this function. 31 32EVP_VerifyUpdate() hashes I<cnt> bytes of data at I<d> into the 33verification context I<ctx>. This function can be called several times on the 34same I<ctx> to include additional data. 35 36EVP_VerifyFinal_ex() verifies the data in I<ctx> using the public key 37I<pkey> and I<siglen> bytes in I<sigbuf>. 38The library context I<libctx> and property query I<propq> are used when creating 39a context to use with the key I<pkey>. 40 41EVP_VerifyFinal() is similar to EVP_VerifyFinal_ex() but uses default 42values of NULL for the library context I<libctx> and the property query I<propq>. 43 44EVP_VerifyInit() initializes verification context I<ctx> to use the default 45implementation of digest I<type>. 46 47=head1 RETURN VALUES 48 49EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for 50failure. 51 52EVP_VerifyFinal_ex() and EVP_VerifyFinal() return 1 for a correct 53signature, 0 for failure and a negative value if some other error occurred. 54 55The error codes can be obtained by L<ERR_get_error(3)>. 56 57=head1 NOTES 58 59The B<EVP> interface to digital signatures should almost always be used in 60preference to the low-level interfaces. This is because the code then becomes 61transparent to the algorithm used and much more flexible. 62 63The call to EVP_VerifyFinal() internally finalizes a copy of the digest context. 64This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can be called 65later to digest and verify additional data. Applications may disable this 66behavior by setting the EVP_MD_CTX_FLAG_FINALISE context flag via 67L<EVP_MD_CTX_set_flags(3)>. 68 69Since only a copy of the digest context is ever finalized the context must 70be cleaned up after use by calling EVP_MD_CTX_free() or a memory leak 71will occur. 72 73Note that not all providers support continuation, in case the selected 74provider does not allow to duplicate contexts EVP_VerifyFinal() will 75finalize the digest context and attempting to process additional data via 76EVP_VerifyUpdate() will result in an error. 77 78=head1 BUGS 79 80Older versions of this documentation wrongly stated that calls to 81EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal(). 82 83Since the public key is passed in the call to EVP_SignFinal() any error 84relating to the private key (for example an unsuitable key and digest 85combination) will not be indicated until after potentially large amounts of 86data have been passed through EVP_SignUpdate(). 87 88It is not possible to change the signing parameters using these function. 89 90The previous two bugs are fixed in the newer EVP_DigestVerify*() function. 91 92=head1 SEE ALSO 93 94L<evp(7)>, 95L<EVP_SignInit(3)>, 96L<EVP_DigestInit(3)>, 97L<evp(7)>, L<HMAC(3)>, L<MD2(3)>, 98L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>, 99L<SHA1(3)>, L<openssl-dgst(1)> 100 101=head1 HISTORY 102 103The function EVP_VerifyFinal_ex() was added in OpenSSL 3.0. 104 105=head1 COPYRIGHT 106 107Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. 108 109Licensed under the Apache License 2.0 (the "License"). You may not use 110this file except in compliance with the License. You can obtain a copy 111in the file LICENSE in the source distribution or at 112L<https://www.openssl.org/source/license.html>. 113 114=cut 115