NAME

EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal, EVP_DigestVerify — EVP signature verification functions

SYNOPSIS

#include <openssl/evp.h>

int
EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, const EVP_MD *type, ENGINE *engine, EVP_PKEY *pkey);

int
EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);

int
EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, const unsigned char *sig, size_t siglen);

int
EVP_DigestVerify(EVP_MD_CTX *ctx, const unsigned char *sig, size_t siglen, const unsigned char *tbs, size_t *tbslen);

DESCRIPTION

The EVP signature routines are a high-level interface to digital signatures.

EVP_DigestVerifyInit() sets up the verification context ctx to use the digest type and the public key pkey. Before calling this function, obtain ctx from EVP_MD_CTX_new(3) or call EVP_MD_CTX_reset(3) on it. The engine argument is always ignored and passing NULL is recommended.

If pctx is not NULL, any pointer passed in as *pctx is ignored and overwritten by an internal pointer to the EVP_PKEY_CTX used by the verification operation: this can be used to set alternative signing options. The returned EVP_PKEY_CTX must not be freed by the application. It is freed automatically when the EVP_MD_CTX is freed.

EVP_DigestVerifyUpdate() hashes cnt bytes of data at d into the verification context ctx. This function can be called several times on the same ctx to include additional data. This function is currently implemented using a macro.

EVP_DigestVerifyFinal() verifies the data in ctx against the signature in sig of length siglen.

EVP_DigestVerify() verifies tbslen bytes at tbs against the signature in sig of length siglen. EVP_DigestVerify() is a one shot operation which verifies a single block of data in one function call. For algorithms that support streaming it is equivalent to calling EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal().

The EVP interface to digital signatures should almost always be used in preference to the low-level interfaces. This is because the code then becomes transparent to the algorithm used and much more flexible.

The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest context. This means that EVP_VerifyUpdate(3) and EVP_VerifyFinal(3) 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_free(3) or a memory leak will occur.

RETURN VALUES

EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0 for failure.

EVP_DigestVerifyFinal() and EVP_DigestVerify() return 1 for success; any other value indicates failure. A return value of 0 indicates that the signature did not verify successfully (that is, the signature did not match the original data or the signature had an invalid form), while other values indicate a more serious error (and sometimes also indicate an invalid signature form).

The error codes can be obtained from ERR_get_error(3).

SEE ALSO

evp(3), EVP_DigestInit(3), EVP_DigestSignInit(3)

HISTORY

EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate(), and EVP_DigestVerifyFinal() first appeared in OpenSSL 1.0.0 and have been available since OpenBSD 4.9.

EVP_DigestVerify() first appeared in OpenSSL 1.1.1 and has been available since OpenBSD 7.0.