diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/EVP_PKEY_verify.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/EVP_PKEY_verify.3 | 395 |
1 files changed, 395 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man3/EVP_PKEY_verify.3 b/secure/lib/libcrypto/man/man3/EVP_PKEY_verify.3 new file mode 100644 index 000000000000..cc23de159372 --- /dev/null +++ b/secure/lib/libcrypto/man/man3/EVP_PKEY_verify.3 @@ -0,0 +1,395 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "EVP_PKEY_VERIFY 3ossl" +.TH EVP_PKEY_VERIFY 3ossl 2025-09-30 3.5.4 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +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 \- signature +verification using a public key algorithm +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #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); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBEVP_PKEY_verify_init()\fR initializes a public key algorithm context \fIctx\fR for +verification using the algorithm given when the context was created +using \fBEVP_PKEY_CTX_new\fR\|(3) or variants thereof. The algorithm is used to +fetch a \fBEVP_SIGNATURE\fR method implicitly, see "Implicit fetch" in \fBprovider\fR\|(7) +for more information about implicit fetches. +.PP +\&\fBEVP_PKEY_verify_init_ex()\fR is the same as \fBEVP_PKEY_verify_init()\fR but additionally +sets the passed parameters \fIparams\fR on the context before returning. +.PP +\&\fBEVP_PKEY_verify_init_ex2()\fR is the same as \fBEVP_PKEY_verify_init_ex()\fR, but works +with an explicitly fetched \fBEVP_SIGNATURE\fR \fIalgo\fR. +A context \fIctx\fR 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 \fBEVP_PKEY_verify()\fR may be pre-determined, and in that +case, those details may normally not be changed. +See "NOTES" below for a deeper explanation. +.PP +\&\fBEVP_PKEY_verify_message_init()\fR initializes a public key algorithm context +\&\fIctx\fR for verifying an unlimited size message using the algorithm given by +\&\fIalgo\fR and the key given through \fBEVP_PKEY_CTX_new\fR\|(3) or +\&\fBEVP_PKEY_CTX_new_from_pkey\fR\|(3). +Passing the message is supported both in a one-shot fashion using +\&\fBEVP_PKEY_verify()\fR, and through the combination of \fBEVP_PKEY_verify_update()\fR and +\&\fBEVP_PKEY_verify_final()\fR. +This function enables using algorithms that can process input of arbitrary +length, such as ED25519, RSA\-SHA256 and similar. +.PP +\&\fBEVP_PKEY_CTX_set_signature()\fR specifies the \fIsiglen\fR bytes long signature +\&\fIsig\fR to be verified against by \fBEVP_PKEY_verify_final()\fR. +It \fImust\fR be used together with \fBEVP_PKEY_verify_update()\fR and +\&\fBEVP_PKEY_verify_final()\fR. +See "NOTES" below for a deeper explanation. +.PP +\&\fBEVP_PKEY_verify_update()\fR adds \fIinlen\fR bytes from \fIin\fR 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. +.PP +\&\fBEVP_PKEY_verify_final()\fR verifies the processed data, given only \fIctx\fR. +The signature to verify against must have been given with +\&\fBEVP_PKEY_CTX_set_signature()\fR. +.PP +\&\fBEVP_PKEY_verify()\fR is a one-shot function that performs the same thing as +\&\fBEVP_PKEY_CTX_set_signature()\fR call with \fIsig\fR and \fIsiglen\fR as parameters, +followed by a single \fBEVP_PKEY_verify_update()\fR call with \fItbs\fR and \fItbslen\fR, +followed by \fBEVP_PKEY_verify_final()\fR call. +.SH NOTES +.IX Header "NOTES" +.SS General +.IX Subsection "General" +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. +.PP +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 \fBEVP_PKEY_verify_init_ex2()\fR or with \fBEVP_PKEY_verify_message_init()\fR. +.PP +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 \fBEVP_PKEY_CTX_set_signature_md\fR\|(3) and +\&\fBEVP_PKEY_CTX_set_rsa_padding\fR\|(3) and similar others), while an RSA\-SHA256 +implementation usually has these details pre-set and immutable. +.PP +The functions described here can't be used to combine separate algorithms. In +particular, neither \fBEVP_PKEY_CTX_set_signature_md\fR\|(3) nor the \fBOSSL_PARAM\fR +parameter "digest" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) 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 \fIctx\fR pre-loaded with an RSA pkey, or +an \fIalgo\fR that fetched \f(CW\*(C`RSA\*(C'\fR and try to specify SHA256 separately to get the +functionality of RSA\-SHA256. If combining algorithms in that manner is +desired, please use \fBEVP_DigestVerifyInit\fR\|(3) and associated functions, or +\&\fBEVP_VerifyInit\fR\|(3) and associated functions. +.SS "Performing multiple verifications" +.IX Subsection "Performing multiple verifications" +When initialized using \fBEVP_PKEY_verify_init_ex()\fR or \fBEVP_PKEY_verify_init_ex2()\fR, +\&\fBEVP_PKEY_verify()\fR can be called more than once on the same context to have +several one-shot operations performed using the same parameters. +.PP +When initialized using \fBEVP_PKEY_verify_message_init()\fR, it's not possible to +call \fBEVP_PKEY_verify()\fR multiple times. +.SS "On \fBEVP_PKEY_CTX_set_signature()\fP" +.IX Subsection "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 \fImust\fR be specified using this function when +using \fBEVP_PKEY_verify_message_update()\fR and \fBEVP_PKEY_verify_message_final()\fR to +perform the verification. +.SH "RETURN VALUES" +.IX Header "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 \fBEVP_PKEY_verify()\fR, +\&\fBEVP_PKEY_verify_recover()\fR and \fBEVP_PKEY_verify_message_final()\fR 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. +.PP +A negative value indicates an error other that signature verification failure. +In particular a return value of \-2 indicates the operation is not supported by +the public key algorithm. +.SH EXAMPLES +.IX Header "EXAMPLES" +.SS "RSA with PKCS#1 padding for SHA256" +.IX Subsection "RSA with PKCS#1 padding for SHA256" +Verify signature using PKCS#1 padding and a SHA256 digest as input: +.PP +.Vb 2 +\& #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. +\& */ +.Ve +.SS "RSA\-SHA256 with a pre-computed digest" +.IX Subsection "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 \f(CW\*(C`sha256WithRSAEncryption\*(C'\fR, +for which the padding is pre-determined to be \fBRSA_PKCS1_PADDING\fR, and the +input digest is assumed to have been computed using SHA256. +.PP +.Vb 2 +\& #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\*(Aqt 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. +\& */ +.Ve +.SS "RSA\-SHA256, one-shot" +.IX Subsection "RSA-SHA256, one-shot" +Verify a document with RSA\-SHA256 using one-shot functions. +To be noted is that RSA\-SHA256 is assumed to be an implementation of +\&\f(CW\*(C`sha256WithRSAEncryption\*(C'\fR, for which the padding is pre-determined to be +\&\fBRSA_PKCS1_PADDING\fR. +.PP +.Vb 2 +\& #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. +\& */ +.Ve +.SS "RSA\-SHA256, using update and final" +.IX Subsection "RSA-SHA256, using update and final" +This is the same as the previous example, but allowing stream-like +functionality. +.PP +.Vb 2 +\& #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. +\& */ +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBEVP_PKEY_CTX_new\fR\|(3), +\&\fBEVP_PKEY_encrypt\fR\|(3), +\&\fBEVP_PKEY_decrypt\fR\|(3), +\&\fBEVP_PKEY_sign\fR\|(3), +\&\fBEVP_PKEY_verify_recover\fR\|(3), +\&\fBEVP_PKEY_derive\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The \fBEVP_PKEY_verify_init()\fR and \fBEVP_PKEY_verify()\fR functions were added in +OpenSSL 1.0.0. +.PP +The \fBEVP_PKEY_verify_init_ex()\fR function was added in OpenSSL 3.0. +.PP +The \fBEVP_PKEY_verify_init_ex2()\fR, \fBEVP_PKEY_verify_message_init()\fR, +\&\fBEVP_PKEY_verify_message_update()\fR, \fBEVP_PKEY_verify_message_final()\fR and +\&\fBEVP_PKEY_CTX_set_signature()\fR functions where added in OpenSSL 3.4. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2006\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +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>. |