EVP_PKEY_VERIFY(3ossl)

📦

version 15.1 · 2 versions

15.1 · freebsd 15.1 (latest)
14.5 · freebsd 14.5

🎀 NAME 🎀

okay so bestie, welcome to the EVP_PKEY_VERIFY(3ossl) page from OpenSSL 💅 this is the whole signature verification using a public key algorithm situation, and the squad of functions on this page is:

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

like, all of them are literally about signature verification using a public key algorithm. no cap. 🫶

✨ SYNOPSIS ✨

#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 vibe, one function at a time, because we are not skipping the lore:

EVP_PKEY_verify_init() — initializes a public key algorithm context ctx for verification using the algorithm that was given when the context was created with EVP_PKEY_CTX_new(3) or variants thereof. That algorithm is used to fetch an EVP_SIGNATURE method implicitly — see "Implicit fetch" in provider(7) for the whole implicit-fetch situation. 👑
EVP_PKEY_verify_init_ex() — same as EVP_PKEY_verify_init() but it also sets the passed parameters params on the context before returning. cute and efficient. ✨
EVP_PKEY_verify_init_ex2() — same as EVP_PKEY_verify_init_ex(), but it works with an explicitly fetched EVP_SIGNATURE algo. A context ctx without a pre-loaded key cannot be used with this function. Depending on what algorithm was 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. See NOTES below for a deeper explanation. 🦋
EVP_PKEY_verify_message_init() — initializes 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). Passing the message is supported both in a one-shot fashion using EVP_PKEY_verify(), and through the combination of EVP_PKEY_verify_update() and EVP_PKEY_verify_final(). This function enables using algorithms that can process input of arbitrary length, such as ED25519, RSA-SHA256 and similar. main character energy fr fr. 🌈
EVP_PKEY_CTX_set_signature() — specifies the siglen bytes long signature sig to be verified against by EVP_PKEY_verify_final(). It must be used together with EVP_PKEY_verify_update() and EVP_PKEY_verify_final(). 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 specification and implementation determine how the input bytes are processed and if there's a limit on the total size of the input. See NOTES below for a deeper explanation. 🎀
EVP_PKEY_verify_final() — verifies the processed data, given only ctx. The signature to verify against must have been given with EVP_PKEY_CTX_set_signature(). periodt. ⭐
EVP_PKEY_verify() — a one-shot function that performs the same thing as an EVP_PKEY_CTX_set_signature() call 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. one function, whole little pipeline, iconic. 💫

🦋 NOTES 🦋

🌸 General 🌸

okay so here's the tea: some signature implementations only accumulate the input data and do no further processing before verifying it — they expect the input to be a digest — while others compress the data, typically by internally producing a digest, and signing the result, which is then verified against a given signature. 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. lowkey crucial. 🧚

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, and 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(). bestie, the algorithm choice is doing a lot of work here. 💜

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, as well as 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 take-backsies, basically. 🔥

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. If combining algorithms in that manner is desired, please use EVP_DigestVerifyInit(3) and associated functions, or EVP_VerifyInit(3) and associated functions. that's the whole assignment. 📚

👑 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 vibe, slay. 💅

When initialized using EVP_PKEY_verify_message_init(), it's not possible to call EVP_PKEY_verify() multiple times. one and done, no encore. 💀

💅 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. timing is everything, bestie. 🎀

⭐ RETURN VALUES ⭐

All functions return 1 for success and 0 or a negative value for failure. However, 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. so 0 is like "nope, didn't match," not "the whole world is on fire." 🙈

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. that's your "algorithm said absolutely not" signal. 💀

✨ EXAMPLES ✨

okay bestie, this is where the page stops being theory and starts being copy-paste-and-adapt energy 🫶 every code block below is exactly what the page gives you — keep the names, the calls, the comments, and the little quirks, periodt. 💅

🔐 RSA with PKCS#1 padding for SHA256

Verify signature using PKCS#1 padding and a SHA256 digest as input — that's the assignment, and here's the 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 /* 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.
 */

the comment at the end is doing the heavy lifting: ret == 1 means success, 0 means verify failure, and < 0 means some other error. no cap. ✨

🧁 RSA-SHA256 with a pre-computed digest

Verify a digest with RSA-SHA256 using one-shot functions. To be noted is that RSA-SHA256 is assumed to be an implementation of "sha256WithRSAEncryption", for which the padding is pre-determined to be RSA_PKCS1_PADDING, and the input digest is assumed to have been computed using SHA256. bestie, read that twice — it's giving very specific 💅

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

again: ret == 1 success, 0 verify failure, < 0 some other error — the little comment fairy says so 🧚

🌈 RSA-SHA256, one-shot

Verify a document with RSA-SHA256 using one-shot functions. Same note as above: RSA-SHA256 is assumed to be an implementation of "sha256WithRSAEncryption", for which the padding is pre-determined to be RSA_PKCS1_PADDING. this one verifies a whole document, not a pre-computed digest — copy block, adapt variables, go off 👑

#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

This is the same as the previous example, but allowing stream-like functionality. so if you like feeding data in chunks, this is your main character moment ✨

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

verbatim copy, punctuation and all 💀 ret == 1 is success, 0 is verify failure, < 0 is some other error. iconic.

👀 SEE ALSO

go read these next, iykyk 💖

🧚 HISTORY

timeline tea ☕ — here's who showed up when:

EVP_PKEY_verify_init() and EVP_PKEY_verify() were added in OpenSSL 1.0.0.
EVP_PKEY_verify_init_ex() was added in OpenSSL 3.0.
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() functions where added in OpenSSL 3.4.

🎀 COPYRIGHT

legal bestie moment, but make it respectful:

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>.

mwah 💖 this absolute icon of a page is from OpenSSL 3.5.6, dated 2026-04-07. go verify something and slay, bestie 🫶✨

📦 where this page comes from

freebsd 15.1: base 15.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms