=head1 NAME
-EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification functions
+EVP_VerifyInit_ex,
+EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal
+- EVP signature verification functions
=head1 SYNOPSIS
#include <openssl/evp.h>
- void EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type);
- void EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
- int EVP_VerifyFinal(EVP_MD_CTX *ctx,unsigned char *sigbuf, unsigned int siglen,EVP_PKEY *pkey);
+ int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
+ int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
+ int EVP_VerifyFinal(EVP_MD_CTX *ctx, unsigned char *sigbuf, unsigned int siglen, EVP_PKEY *pkey);
+
+ int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type);
=head1 DESCRIPTION
The EVP signature verification routines are a high level interface to digital
signatures.
-EVP_VerifyInit() initializes a verification context B<ctx> to using digest
-B<type>: this will typically be supplied by a function such as EVP_sha1().
+EVP_VerifyInit_ex() sets up verification context B<ctx> to use digest
+B<type> from ENGINE B<impl>. B<ctx> must be created by calling
+EVP_MD_CTX_new() before calling this function.
EVP_VerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
verification context B<ctx>. This function can be called several times on the
same B<ctx> to include additional data.
EVP_VerifyFinal() verifies the data in B<ctx> using the public key B<pkey>
-and against the B<siglen> bytes at B<sigbuf>. After calling EVP_VerifyFinal()
-no additional calls to EVP_VerifyUpdate() can be made, but EVP_VerifyInit()
-can be called to initialize a new verification operation.
+and against the B<siglen> bytes at B<sigbuf>.
+
+EVP_VerifyInit() initializes verification context B<ctx> to use the default
+implementation of digest B<type>.
=head1 RETURN VALUES
-EVP_VerifyInit() and EVP_VerifyUpdate() do not return values.
+EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for
+failure.
EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if some
other error occurred.
-The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+The error codes can be obtained by L<ERR_get_error(3)>.
=head1 NOTES
Due to the link between message digests and public key algorithms the correct
digest algorithm must be used with the correct public key type. A list of
-algorithms and associated public key algorithms appears in
-L<EVP_DigestInit(3)|EVP_DigestInit(3)>.
+algorithms and associated public key algorithms appears in
+L<EVP_DigestInit(3)>.
+
+The call to EVP_VerifyFinal() internally finalizes a copy of the digest context.
+This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can be called
+later to digest and verify additional data.
+
+Since only a copy of the digest context is ever finalized the context must
+be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak
+will occur.
=head1 BUGS
-Several of the functions do not return values: maybe they should. Although the
-internal digest operations will never fail some future hardware based operations
-might.
+Older versions of this documentation wrongly stated that calls to
+EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal().
+
+Since the public key is passed in the call to EVP_SignFinal() any error
+relating to the private key (for example an unsuitable key and digest
+combination) will not be indicated until after potentially large amounts of
+data have been passed through EVP_SignUpdate().
+
+It is not possible to change the signing parameters using these function.
+
+The previous two bugs are fixed in the newer EVP_VerifyDigest*() function.
=head1 SEE ALSO
-L<evp(3)|evp(3)>,
-L<EVP_SignInit(3)|EVP_SignInit(3)>,
-L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>,
-L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
-L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>,
-L<sha(3)|sha(3)>, L<digest(1)|digest(1)>
+L<evp(3)>,
+L<EVP_SignInit(3)>,
+L<EVP_DigestInit(3)>, L<err(3)>,
+L<evp(3)>, L<hmac(3)>, L<md2(3)>,
+L<md5(3)>, L<mdc2(3)>, L<ripemd(3)>,
+L<sha(3)>, L<dgst(1)>
+
+=head1 COPYRIGHT
-=head1 HISTORY
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
-EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are
-available in all versions of SSLeay and OpenSSL.
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
=cut
projects / thirdparty / openssl.git / blobdiff