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.
66
67Since only a copy of the digest context is ever finalized the context must
68be cleaned up after use by calling EVP_MD_CTX_free() or a memory leak
69will occur.
70
71=head1 BUGS
72
73Older versions of this documentation wrongly stated that calls to
74EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal().
75
76Since the public key is passed in the call to EVP_SignFinal() any error
77relating to the private key (for example an unsuitable key and digest
78combination) will not be indicated until after potentially large amounts of
79data have been passed through EVP_SignUpdate().
80
81It is not possible to change the signing parameters using these function.
82
83The previous two bugs are fixed in the newer EVP_DigestVerify*() function.
84
85=head1 SEE ALSO
86
87L<evp(7)>,
88L<EVP_SignInit(3)>,
89L<EVP_DigestInit(3)>,
90L<evp(7)>, L<HMAC(3)>, L<MD2(3)>,
91L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>,
92L<SHA1(3)>, L<openssl-dgst(1)>
93
94=head1 HISTORY
95
96The function EVP_VerifyFinal_ex() was added in OpenSSL 3.0.
97
98=head1 COPYRIGHT
99
100Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
101
102Licensed under the Apache License 2.0 (the "License").  You may not use
103this file except in compliance with the License.  You can obtain a copy
104in the file LICENSE in the source distribution or at
105L<https://www.openssl.org/source/license.html>.
106
107=cut
108