EVP_PKEY_VERIFY(3SSL)

💖 EVP_PKEY_VERIFY 💖

okay bestie, gather round, because this is the EVP_PKEY_VERIFY(3SSL) joint — aka signature verification using a public key algorithm ✨. It's from OpenSSL, it's long, and we're doing it in 2 parts, so buckle up buttercup 🎀

---

✨ SYNOPSIS ✨

like, here's the whole squad of functions in one block, no edits, no notes:

#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 🌸

okay so here's the tea on every single one of these 🫖

• EVP_PKEY_verify_init() — sets up a public key algorithm context ctx for verification, using whatever algorithm was handed over when the context got created with EVP_PKEY_CTX_new(3) or any of its little siblings. That algorithm is used to fetch an EVP_SIGNATURE method implicitly — if you wanna know the whole lore on implicit fetches, go read "Implicit fetch" in provider(7). iykyk 💅
• EVP_PKEY_verify_init_ex() — literally the same as EVP_PKEY_verify_init() except it also slaps the params params onto the context before it returns. extra, but in a good way ✨
• EVP_PKEY_verify_init_ex2() — same energy as EVP_PKEY_verify_init_ex(), but it rolls with an explicitly fetched EVP_SIGNATURE algo. Heads up though: a context ctx with no pre-loaded key is a no for this function, can't do it. And depending on which algorithm got fetched, some details about how the input to EVP_PKEY_verify() is treated might already be pre-determined, and in that case those details usually can't be changed. There's a whole "NOTES" section below for the deep dive, keep scrolling 📜
• EVP_PKEY_verify_message_init() — inits a public key algorithm context ctx for verifying a message of unlimited size, using the algorithm in algo and the key you gave through EVP_PKEY_CTX_new(3) or EVP_PKEY_CTX_new_from_pkey(3). You can pass the message two ways: one-shot style with EVP_PKEY_verify(), or the combo meal of EVP_PKEY_verify_message_update() + EVP_PKEY_verify_message_final(). This one's the icon that unlocks algorithms handling arbitrary-length input — think ED25519, RSA-SHA256, that whole crew 👑
• EVP_PKEY_CTX_set_signature() — tells the context about the signature sig (which is siglen bytes long) that EVP_PKEY_verify_message_final() is gonna verify against. It must be used together with EVP_PKEY_verify_message_update() and EVP_PKEY_verify_message_final(). There's more explanation down in "NOTES", don't worry 🧚
• EVP_PKEY_verify_message_update() — adds inlen bytes from in to the data that's getting processed for verification. How those input bytes actually get chewed on, and whether there's a cap on total input size, is up to the signature algorithm spec + implementation. Again: "NOTES" below, bestie 💜
• EVP_PKEY_verify_message_final() — verifies the processed data, and you literally just hand it ctx. The signature it's verifying against must have already been given via EVP_PKEY_CTX_set_signature(). no signature, no verification, periodt 🚫
• EVP_PKEY_verify() — the one-shot icon 🎯. It does the exact same thing as calling EVP_PKEY_CTX_set_signature() with sig and siglen as the parameters, then a single EVP_PKEY_verify_message_update() call with tbs and tbslen, then EVP_PKEY_verify_message_final(). Three steps, one function call, we love efficiency.

---

📝 NOTES 📝

General

Some signature implementations are lazy girlies — they just accumulate the input data and do zero further processing before verifying (they're expecting the input to be a digest). Others compress the data, usually by internally making a digest, signing the result, and then verifying against a given signature. And some of them? They support both modes at the same time, overachievers 😭. The caller is expected to know how the chosen algorithm is supposed to behave, and under what conditions. that's on you, babe.

For example (✨ examples, we love her):

• 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. produce the digest internally
• and RSA-SHA256 can be expected to handle either mode of operation, depending on whether the operation was initialized with EVP_PKEY_verify_init_ex2() or with EVP_PKEY_verify_message_init()

Similarly, an RSA implementation usually expects extra details to be set — like the message digest algorithm the input is supposed to be digested with, plus the padding mode (peep EVP_PKEY_CTX_set_signature_md(3) and EVP_PKEY_CTX_set_rsa_padding(3) and similar others). Meanwhile an RSA-SHA256 implementation usually has all those details pre-set and immutable. no touching 🔒

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: you can't take a ctx pre-loaded with an RSA pkey, or an algo that fetched "RSA", and then try to specify SHA256 separately to fake the functionality of RSA-SHA256. It does not work like that, bestie. If you do want to combine algorithms that way, please go use EVP_DigestVerifyInit(3) and associated functions, or EVP_VerifyInit(3) and associated functions. 🙏

Performing multiple verifications

• when initialized using EVP_PKEY_verify_init_ex() or EVP_PKEY_verify_init_ex2(), you can call EVP_PKEY_verify() more than once on the same context — multiple one-shot operations, same parameters, we're reusing, we're sustainable ♻️
• when initialized using EVP_PKEY_verify_message_init(), it is not possible to call EVP_PKEY_verify() multiple times. one and done.

On EVP_PKEY_CTX_set_signature()

Some signature algorithms (such as LMS) require the signature verification data to be specified before verifying the message. Other algorithms are chill and let the signature show up late. To support either way (which may depend on how your application's input actually flows in), the signature you're verifying against must be specified using this function when you're using EVP_PKEY_verify_message_update() and EVP_PKEY_verify_message_final() to do the verification. So like, EVP_PKEY_CTX_set_signature() is the moment the signature enters the chat 💅

---

🫶 RETURN VALUES 🫶

All functions return 1 for success, and 0 or a negative value for failure. easy.

but WAIT — 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 (i.e. tbs did not match the original data, or the signature was of invalid form). It is not an indication of a more serious error. don't panic, it's just a no ❌

A negative value indicates an error other than signature verification failure. And specifically: a return value of -2 indicates the operation is not supported by the public key algorithm 🚩

---

(part 1 done, part 2 is coming, don't go anywhere 🌈)

okay bestie we did the boring theory parts, and now it's time for the part everyone actually came for: the code. copy-paste these bad boys, they're iconic.

---

🎀 EXAMPLES 🎀

RSA with PKCS#1 padding for SHA256

ok so we're verifying a signature with PKCS#1 padding and a SHA256 digest as the input. slay:

#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);
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.
 */

bestie note: ret == 1 is the 💖success💖 vibe, 0 means the verify straight up failed, and < 0 means something else went wrong. three outcomes, one variable, no cap.

---

RSA-SHA256 with a pre-computed digest

here we verify a digest with RSA-SHA256 using the one-shot functions. and listen, important lore: 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. it's giving already decided for you 💅

#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);
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.
 */

😭 yes the /* Determine buffer length */ comment is right there before the actual verify call, and yes the verify call appears twice. we do not touch the source material. we respect the ancestors. keep it literally as-is.

---

RSA-SHA256, one-shot

now we're verifying a whole document with RSA-SHA256 using the one-shot functions. same lore as before: RSA-SHA256 is assumed to be an implementation of "sha256WithRSAEncryption", for which 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);
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.
 */

and once again for the people in the back: ret == 1 slays, 0 is a verify fail, < 0 is some other error. 🫶

---

RSA-SHA256, using update and final

same thing as the last one, but now we get stream-like functionality. feed it in chunks, main character energy ✨

#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);
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.
 */

💀 real talk: that if (EVP_PKEY_verify_message_update(ctx, in, inlen)) <= 0) line has an extra ) sitting pretty in there. that's literally what the page says, so that's what you get. don't come for me, i just work here. 🙈

---

🌸 SEE ALSO 🌸

go read your sisters bestie, they're all icons:

• EVP_PKEY_CTX_new(3)
• EVP_PKEY_encrypt(3)
• EVP_PKEY_decrypt(3)
• EVP_PKEY_sign(3)
• EVP_PKEY_verify_recover(3)
• EVP_PKEY_derive(3)

---

💜 HISTORY 💜

the timeline of how we got here, because context matters:

• EVP_PKEY_verify_init() and EVP_PKEY_verify() — added in OpenSSL 1.0.0. the OGs. 👑
• EVP_PKEY_verify_init_ex() — added in OpenSSL 3.0. a 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() — where added in OpenSSL 3.4. yes, the page says "where added". we keep it fr fr. the whole streaming squad arrived together. 🔥

---

⭐ COPYRIGHT ⭐

Copyright 2006-2025 The OpenSSL Project Authors. All Rights Reserved.

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 the whole page bestie, we ate and left no crumbs 💅 this was EVP_PKEY_VERIFY(3SSL) from source version 4.0.3, dated 2026-09-29. go forth and verify some signatures, you're literally a cryptographer now 🎀✨🦋