EVP_PKEY_VERIFY(3ossl)

📦

version 3.5.9 · 8 versions

3.5.9 · fedora 43, fedora 44 (latest)
3.5.9 · centos-stream 9
3.5.9 · centos-stream 10
3.5.9 · alpine 3.22
3.5.9 · alpine 3.23, alpine 3.24
3.5.8 · fedora 43
3.5.1 · fedora 43
3.5.5 · fedora 44

✨ NAME ✨

okay bestie, welcome to the EVP_PKEY_VERIFY(3ossl) page 💖 — this is the manual for signature verification using a public key algorithm, and the whole squad is here:

EVP_PKEY_verify_init
EVP_PKEY_verify_init_ex
EVP_PKEY_verify_init_ex2
EVP_PKEY_verify
EVP_PKEY_verify_message_init
EVP_PKEY_verify_message_update
EVP_PKEY_verify_message_final
EVP_PKEY_CTX_set_signature

that's the whole cast, no cap 🌸

🦋 SYNOPSIS 🦋

like, here's the vibe, literally verbatim:

#include <openssl/evp.h>

int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx);
int EVP_PKEY_verify_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
int EVP_PKEY_verify_init_ex2(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo,
                             const OSSL_PARAM params[]);
int EVP_PKEY_verify_message_init(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo,
                                 const OSSL_PARAM params[]);
int EVP_PKEY_CTX_set_signature(EVP_PKEY_CTX *pctx,
                               const unsigned char *sig, size_t siglen);
int EVP_PKEY_verify_message_update(EVP_PKEY_CTX *ctx,
                                   unsigned char *in, size_t inlen);
int EVP_PKEY_verify_message_final(EVP_PKEY_CTX *ctx);
int EVP_PKEY_verify(EVP_PKEY_CTX *ctx,
                    const unsigned char *sig, size_t siglen,
                    const unsigned char *tbs, size_t tbslen);

💅 DESCRIPTION 💅

EVP_PKEY_verify_init() sets up a public key algorithm context ctx for verification, using the algorithm that was given back when the context got created with EVP_PKEY_CTX_new(3) or one of its variants. That algorithm is what gets used to fetch an EVP_SIGNATURE method implicitly — go peek at "Implicit fetch" in provider(7) if you wanna know more about implicit fetches, iykyk 🔍

EVP_PKEY_verify_init_ex() is giving the exact same energy as EVP_PKEY_verify_init(), except it also sets the passed parameters params on the context before it returns. extra credit behavior, we love it ✨

EVP_PKEY_verify_init_ex2() is the same as EVP_PKEY_verify_init_ex(), but it works with an explicitly fetched EVP_SIGNATURE algo. ⚠️ Important: a context ctx without a pre-loaded key cannot be used with this function, periodt. And depending on which algorithm got fetched, certain details revolving around the treatment of the input to EVP_PKEY_verify() may be pre-determined — and in that case, those details may normally not be changed. Wanna go deeper? The "NOTES" section below has you covered 🫶

EVP_PKEY_verify_message_init() sets up a public key algorithm context ctx for verifying an unlimited size message, using the algorithm given by algo and the key given through EVP_PKEY_CTX_new(3) or EVP_PKEY_CTX_new_from_pkey(3). You can pass the message in a one-shot fashion with EVP_PKEY_verify(), or through the combo of EVP_PKEY_verify_update() and EVP_PKEY_verify_final(). This function is what enables using algorithms that can process input of arbitrary length — think ED25519, RSA-SHA256 and similar 👑

EVP_PKEY_CTX_set_signature() specifies the siglen bytes long signature sig that EVP_PKEY_verify_final() is gonna verify against. It must be used together with EVP_PKEY_verify_update() and EVP_PKEY_verify_final() — no solo missions. See "NOTES" below for a deeper explanation 🔥

EVP_PKEY_verify_update() adds inlen bytes from in to the data to be processed for verification. The signature algorithm spec and implementation decide how the input bytes get processed and whether there's a limit on the total size of the input. Again: "NOTES" below, deeper explanation, go read it 💜

EVP_PKEY_verify_final() verifies the processed data, given only ctx. The signature it verifies against must have been given with EVP_PKEY_CTX_set_signature().

EVP_PKEY_verify() is the one-shot girlie 🌈 — it does the same thing as calling EVP_PKEY_CTX_set_signature() with sig and siglen as parameters, followed by a single EVP_PKEY_verify_update() call with tbs and tbslen, followed by an EVP_PKEY_verify_final() call. three steps, one function, iconic.

🌸 NOTES 🌸

🎀 General

okay so, some signature implementations just accumulate the input data and do no further processing before verifying it — they're expecting the input to already be a digest. Others compress the data, typically by internally producing a digest, and signing the result, which then gets verified against a given signature. And some of them support both modes of operation at the same time. 😭 The caller is expected to know how the chosen algorithm is supposed to behave and under what conditions. that's on you, bestie.

for example:

an RSA implementation can be expected to only expect a digest as input
while ED25519 can be expected to process the input with a hash, i.e. to produce the digest internally
while RSA-SHA256 can be expected to handle either mode of operation, depending on if the operation was initialized with EVP_PKEY_verify_init_ex2() or with EVP_PKEY_verify_message_init()

similarly, an RSA implementation usually expects additional details to be set — like the message digest algorithm that the input is supposed to be digested with, plus the padding mode (see EVP_PKEY_CTX_set_signature_md(3) and EVP_PKEY_CTX_set_rsa_padding(3) and similar others) — while an RSA-SHA256 implementation usually has these details pre-set and immutable. no takebacks. 💀

BIG ONE: the functions described here can't be used to combine separate algorithms. in particular, neither EVP_PKEY_CTX_set_signature_md(3) nor the OSSL_PARAM parameter "digest" (OSSL_SIGNATURE_PARAM_DIGEST) can be used to combine a signature algorithm with a hash algorithm to process the input. in other words: it's not possible to specify a ctx pre-loaded with an RSA pkey, or an algo that fetched "RSA", and try to specify SHA256 separately to get the functionality of RSA-SHA256. nope, not happening 🙈

if combining algorithms in that manner is what you want, please use EVP_DigestVerifyInit(3) and associated functions, or EVP_VerifyInit(3) and associated functions. that's the way 🫶

🦋 Performing multiple verifications

when initialized using EVP_PKEY_verify_init_ex() or EVP_PKEY_verify_init_ex2(), EVP_PKEY_verify() can be called more than once on the same context, to have several one-shot operations performed using the same parameters. reusing the setup, sustainable queen ✨

when initialized using EVP_PKEY_verify_message_init(), it's not possible to call EVP_PKEY_verify() multiple times. one and done, no reruns 💅

⭐ On `EVP_PKEY_CTX_set_signature()`

some signature algorithms (such as LMS) require the signature verification data be specified before verifying the message. other algorithms allow the signature to be specified late. to allow either way — which may depend on the application's flow of input — the signature to be verified against must be specified using this function when using EVP_PKEY_verify_message_update() and EVP_PKEY_verify_message_final() to perform the verification. flexible, but you gotta play by the rules 🌈

👑 RETURN VALUES 👑

all functions return 1 for success and 0 or a negative value for failure. ✨

but here's the plot twist, bestie: unlike other functions, the return value 0 from EVP_PKEY_verify(), EVP_PKEY_verify_recover() and EVP_PKEY_verify_message_final() only indicates that the signature did not verify successfully — that is, tbs did not match the original data, or the signature was of invalid form. it is not an indication of a more serious error. 😌

a negative value indicates an error other than signature verification failure. in particular, a return value of -2 indicates the operation is not supported by the public key algorithm. 💀

✨ EXAMPLES ✨

okay bestie, real talk — this is where it all clicks. four lil scenarios, copy-paste energy, let's go 💅

🌸 RSA with PKCS#1 padding for SHA256

Verify a signature using PKCS#1 padding, with a SHA256 digest as the input. iconic, classic, does what it says 🫶

#include <openssl/evp.h>
#include <openssl/rsa.h>

EVP_PKEY_CTX *ctx;
unsigned char *md, *sig;
size_t mdlen, siglen;
EVP_PKEY *verify_key;

/*
 * NB: assumes verify_key, sig, siglen md and mdlen are already set up
 * and that verify_key is an RSA public key
 */
ctx = EVP_PKEY_CTX_new(verify_key, NULL /* no engine */);
if (ctx == NULL)
    /* Error occurred */
if (EVP_PKEY_verify_init(ctx) <= 0)
    /* Error */
if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
    /* Error */
if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
    /* Error */

/* Perform operation */
ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen);

/*
 * ret == 1 indicates success, 0 verify failure and < 0 for some
 * other error.
 */

🦋 RSA-SHA256 with a pre-computed digest

Verify a digest with RSA-SHA256 using the one-shot functions. Important lore alert: RSA-SHA256 is assumed to be an implementation of "sha256WithRSAEncryption", which means the padding is pre-determined to be RSA_PKCS1_PADDING, and the input digest is assumed to have been computed using SHA256. no takebacks, that's just the deal 💀

#include <openssl/evp.h>
#include <openssl/rsa.h>

EVP_PKEY_CTX *ctx;
/* md is a SHA-256 digest in this example. */
unsigned char *md, *sig;
size_t mdlen = 32, siglen;
EVP_PKEY *signing_key;

/*
 * NB: assumes verify_key, sig, siglen, md and mdlen are already set up
 * and that verify_key is an RSA public key
 */
ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL);

if (ctx == NULL)
    /* Error occurred */
if (EVP_PKEY_verify_init_ex2(ctx, alg, NULL) <= 0)
    /* Error */

/* Determine buffer length */
if (EVP_PKEY_verify(ctx, sig, siglen, md, mdlen) <= 0)
    /* Error or signature doesn't verify */

/* Perform operation */
ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen);

/*
 * ret == 1 indicates success, 0 verify failure and < 0 for some
 * other error.
 */

🎀 RSA-SHA256, one-shot

Verify a whole document with RSA-SHA256 using the one-shot functions. same deal as before, bestie: RSA-SHA256 is assumed to be an implementation of "sha256WithRSAEncryption", so the padding is pre-determined to be RSA_PKCS1_PADDING ✨

#include <openssl/evp.h>
#include <openssl/rsa.h>

EVP_PKEY_CTX *ctx;
/* in the input in this example. */
unsigned char *in, *sig;
/* inlen is the length of the input in this example. */
size_t inlen, siglen;
EVP_PKEY *signing_key;
EVP_SIGNATURE *alg;

/*
 * NB: assumes signing_key, in and inlen are set up before
 * the next step. signing_key must be an RSA private key,
 * in must point to data to be digested and signed, and
 * inlen must be the size of the data in bytes.
 */
ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL);

if (ctx == NULL || alg == NULL)
    /* Error occurred */
if (EVP_PKEY_verify_message_init(ctx, alg, NULL) <= 0)
    /* Error */

/* Perform operation */
ret = EVP_PKEY_verify(ctx, sig, siglen, in, inlen);

/*
 * ret == 1 indicates success, 0 verify failure and < 0 for some
 * other error.
 */

💜 RSA-SHA256, using update and final

same as the previous one, except now it's giving stream-like functionality — feed it in chunks, no need to hold the whole thing at once 🌈

#include <openssl/evp.h>
#include <openssl/rsa.h>

EVP_PKEY_CTX *ctx;
/* in is the input in this example. */
unsigned char *in, *sig;
/* inlen is the length of the input in this example. */
size_t inlen, siglen;
EVP_PKEY *signing_key;
EVP_SIGNATURE *alg;

/*
 * NB: assumes signing_key, in and inlen are set up before
 * the next step. signing_key must be an RSA private key,
 * in must point to data to be digested and signed, and
 * inlen must be the size of the data in bytes.
 */
ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
alg = EVP_SIGNATURE_fetch(NULL, "RSA-SHA256", NULL);

if (ctx == NULL || alg == NULL)
    /* Error occurred */
if (EVP_PKEY_verify_message_init(ctx, alg, NULL) <= 0)
    /* Error */

/* We have the signature, specify it early */
EVP_PKEY_CTX_set_signature(ctx, sig, siglen);

/* Perform operation */
while (inlen > 0) {
    if (EVP_PKEY_verify_message_update(ctx, in, inlen)) <= 0)
        /* Error */
    if (inlen > 256) {
        inlen -= 256;
        in += 256;
    } else {
        inlen = 0;
    }
}
ret = EVP_PKEY_verify_message_final(ctx);

/*
 * ret == 1 indicates success, 0 verify failure and < 0 for some
 * other error.
 */

👑 SEE ALSO 👑

go read these next, they're the friend group 💖

📜 HISTORY 📜

the lore drop, in order 🧚

EVP_PKEY_verify_init() and EVP_PKEY_verify() showed up in OpenSSL 1.0.0. vintage, but make it work.
EVP_PKEY_verify_init_ex() arrived in OpenSSL 3.0. glow up era ✨
EVP_PKEY_verify_init_ex2(), EVP_PKEY_verify_message_init(), EVP_PKEY_verify_message_update(), EVP_PKEY_verify_message_final() and EVP_PKEY_CTX_set_signature() were added in OpenSSL 3.4. the new girls on the block, and they ate 💅

Licensed under the Apache License 2.0 (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 <https://www.openssl.org/source/license.html>.

and that's a wrap, bestie 🫶 this was EVP_PKEY_VERIFY(3ossl) from the OpenSSL 3.5.9 manual pages, dated 2026-09-29. verify your signatures, hydrate, and go touch some grass 🌸💖

📦 where this page comes from

fedora 43: openssl-devel 1:3.5.9-1.fc43 · Apache-2.0
fedora 43: openssl-devel 1:3.5.9-1.fc43 · Apache-2.0
fedora 44: openssl-devel 1:3.5.9-1.fc44 · Apache-2.0
fedora 44: openssl-devel 1:3.5.9-1.fc44 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms