Debian Codegraph @

upstream/debian-unstable/man3/EVP_PKEY_verify.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EVP_PKEY_VERIFY 3SSL"
58 .TH EVP_PKEY_VERIFY 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EVP_PKEY_verify_init, EVP_PKEY_verify_init_ex, EVP_PKEY_verify_init_ex2,
65 EVP_PKEY_verify, EVP_PKEY_verify_message_init, EVP_PKEY_verify_message_update,
66 EVP_PKEY_verify_message_final, EVP_PKEY_CTX_set_signature \- signature
67 verification using a public key algorithm
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/evp.h>
72 \&
73 \& int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx);
74 \& int EVP_PKEY_verify_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
75 \& int EVP_PKEY_verify_init_ex2(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo,
76 \& const OSSL_PARAM params[]);
77 \& int EVP_PKEY_verify_message_init(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo,
78 \& const OSSL_PARAM params[]);
79 \& int EVP_PKEY_CTX_set_signature(EVP_PKEY_CTX *pctx,
80 \& const unsigned char *sig, size_t siglen);
81 \& int EVP_PKEY_verify_message_update(EVP_PKEY_CTX *ctx,
82 \& unsigned char *in, size_t inlen);
83 \& int EVP_PKEY_verify_message_final(EVP_PKEY_CTX *ctx);
84 \& int EVP_PKEY_verify(EVP_PKEY_CTX *ctx,
85 \& const unsigned char *sig, size_t siglen,
86 \& const unsigned char *tbs, size_t tbslen);
87 .Ve
88 .SH DESCRIPTION
89 .IX Header "DESCRIPTION"
90 \&\fBEVP_PKEY_verify_init()\fR initializes a public key algorithm context \fIctx\fR for
91 verification using the algorithm given when the context was created
92 using \fBEVP_PKEY_CTX_new\fR\|(3) or variants thereof. The algorithm is used to
93 fetch a \fBEVP_SIGNATURE\fR method implicitly, see "Implicit fetch" in \fBprovider\fR\|(7)
94 for more information about implicit fetches.
95 .PP
96 \&\fBEVP_PKEY_verify_init_ex()\fR is the same as \fBEVP_PKEY_verify_init()\fR but additionally
97 sets the passed parameters \fIparams\fR on the context before returning.
98 .PP
99 \&\fBEVP_PKEY_verify_init_ex2()\fR is the same as \fBEVP_PKEY_verify_init_ex()\fR, but works
100 with an explicitly fetched \fBEVP_SIGNATURE\fR \fIalgo\fR.
101 A context \fIctx\fR without a pre-loaded key cannot be used with this function.
102 Depending on what algorithm was fetched, certain details revolving around the
103 treatment of the input to \fBEVP_PKEY_verify()\fR may be pre-determined, and in that
104 case, those details may normally not be changed.
105 See "NOTES" below for a deeper explanation.
106 .PP
107 \&\fBEVP_PKEY_verify_message_init()\fR initializes a public key algorithm context
108 \&\fIctx\fR for verifying an unlimited size message using the algorithm given by
109 \&\fIalgo\fR and the key given through \fBEVP_PKEY_CTX_new\fR\|(3) or
110 \&\fBEVP_PKEY_CTX_new_from_pkey\fR\|(3).
111 Passing the message is supported both in a one-shot fashion using
112 \&\fBEVP_PKEY_verify()\fR, and through the combination of
113 \&\fBEVP_PKEY_verify_message_update()\fR and \fBEVP_PKEY_verify_message_final()\fR.
114 This function enables using algorithms that can process input of arbitrary
115 length, such as ED25519, RSA\-SHA256 and similar.
116 .PP
117 \&\fBEVP_PKEY_CTX_set_signature()\fR specifies the \fIsiglen\fR bytes long signature
118 \&\fIsig\fR to be verified against by \fBEVP_PKEY_verify_message_final()\fR.
119 It \fImust\fR be used together with \fBEVP_PKEY_verify_message_update()\fR and
120 \&\fBEVP_PKEY_verify_message_final()\fR.
121 See "NOTES" below for a deeper explanation.
122 .PP
123 \&\fBEVP_PKEY_verify_message_update()\fR adds \fIinlen\fR bytes from \fIin\fR to the data
124 to be processed for verification. The signature algorithm specification and
125 implementation determine how the input bytes are processed and if there's a
126 limit on the total size of the input. See "NOTES" below for a deeper
127 explanation.
128 .PP
129 \&\fBEVP_PKEY_verify_message_final()\fR verifies the processed data, given only \fIctx\fR.
130 The signature to verify against must have been given with
131 \&\fBEVP_PKEY_CTX_set_signature()\fR.
132 .PP
133 \&\fBEVP_PKEY_verify()\fR is a one-shot function that performs the same thing as
134 \&\fBEVP_PKEY_CTX_set_signature()\fR call with \fIsig\fR and \fIsiglen\fR as parameters,
135 followed by a single \fBEVP_PKEY_verify_message_update()\fR call with \fItbs\fR and
136 \&\fItbslen\fR, followed by \fBEVP_PKEY_verify_message_final()\fR call.
137 .SH NOTES
138 .IX Header "NOTES"
139 .SS General
140 .IX Subsection "General"
141 Some signature implementations only accumulate the input data and do no
142 further processing before verifying it (they expect the input to be a digest),
143 while others compress the data, typically by internally producing a digest,
144 and signing the result, which is then verified against a given signature.
145 Some of them support both modes of operation at the same time.
146 The caller is expected to know how the chosen algorithm is supposed to behave
147 and under what conditions.
148 .PP
149 For example, an RSA implementation can be expected to only expect a digest as
150 input, while ED25519 can be expected to process the input with a hash, i.e.
151 to produce the digest internally, and while RSA\-SHA256 can be expected to
152 handle either mode of operation, depending on if the operation was initialized
153 with \fBEVP_PKEY_verify_init_ex2()\fR or with \fBEVP_PKEY_verify_message_init()\fR.
154 .PP
155 Similarly, an RSA implementation usually expects additional details to be set,
156 like the message digest algorithm that the input is supposed to be digested
157 with, as well as the padding mode (see \fBEVP_PKEY_CTX_set_signature_md\fR\|(3) and
158 \&\fBEVP_PKEY_CTX_set_rsa_padding\fR\|(3) and similar others), while an RSA\-SHA256
159 implementation usually has these details pre-set and immutable.
160 .PP
161 The functions described here can't be used to combine separate algorithms. In
162 particular, neither \fBEVP_PKEY_CTX_set_signature_md\fR\|(3) nor the \fBOSSL_PARAM\fR
163 parameter "digest" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) can be used to combine a
164 signature algorithm with a hash algorithm to process the input. In other
165 words, it's not possible to specify a \fIctx\fR pre-loaded with an RSA pkey, or
166 an \fIalgo\fR that fetched \f(CW\*(C`RSA\*(C'\fR and try to specify SHA256 separately to get the
167 functionality of RSA\-SHA256. If combining algorithms in that manner is
168 desired, please use \fBEVP_DigestVerifyInit\fR\|(3) and associated functions, or
169 \&\fBEVP_VerifyInit\fR\|(3) and associated functions.
170 .SS "Performing multiple verifications"
171 .IX Subsection "Performing multiple verifications"
172 When initialized using \fBEVP_PKEY_verify_init_ex()\fR or \fBEVP_PKEY_verify_init_ex2()\fR,
173 \&\fBEVP_PKEY_verify()\fR can be called more than once on the same context to have
174 several one-shot operations performed using the same parameters.
175 .PP
176 When initialized using \fBEVP_PKEY_verify_message_init()\fR, it's not possible to
177 call \fBEVP_PKEY_verify()\fR multiple times.
178 .SS "On \fBEVP_PKEY_CTX_set_signature()\fP"
179 .IX Subsection "On EVP_PKEY_CTX_set_signature()"
180 Some signature algorithms (such as LMS) require the signature verification
181 data be specified before verifying the message.
182 Other algorithms allow the signature to be specified late.
183 To allow either way (which may depend on the application's flow of input), the
184 signature to be verified against \fImust\fR be specified using this function when
185 using \fBEVP_PKEY_verify_message_update()\fR and \fBEVP_PKEY_verify_message_final()\fR to
186 perform the verification.
187 .SH "RETURN VALUES"
188 .IX Header "RETURN VALUES"
189 All functions return 1 for success and 0 or a negative value for failure.
190 However, unlike other functions, the return value 0 from \fBEVP_PKEY_verify()\fR,
191 \&\fBEVP_PKEY_verify_recover()\fR and \fBEVP_PKEY_verify_message_final()\fR only indicates
192 that the signature did not verify successfully (that is tbs did not match the
193 original data or the signature was of invalid form) it is not an indication of
194 a more serious error.
195 .PP
196 A negative value indicates an error other that signature verification failure.
197 In particular a return value of \-2 indicates the operation is not supported by
198 the public key algorithm.
199 .SH EXAMPLES
200 .IX Header "EXAMPLES"
201 .SS "RSA with PKCS#1 padding for SHA256"
202 .IX Subsection "RSA with PKCS#1 padding for SHA256"
203 Verify signature using PKCS#1 padding and a SHA256 digest as input:
204 .PP
205 .Vb 2
206 \& #include <openssl/evp.h>
207 \& #include <openssl/rsa.h>
208 \&
209 \& EVP_PKEY_CTX *ctx;
210 \& unsigned char *md, *sig;
211 \& size_t mdlen, siglen;
212 \& EVP_PKEY *verify_key;
213 \&
214 \& /*
215 \& * NB: assumes verify_key, sig, siglen md and mdlen are already set up
216 \& * and that verify_key is an RSA public key
217 \& */
218 \& ctx = EVP_PKEY_CTX_new(verify_key, NULL /* no engine */);
219 \& if (ctx == NULL)
220 \& /* Error occurred */
221 \& if (EVP_PKEY_verify_init(ctx) <= 0)
222 \& /* Error */
223 \& if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
224 \& /* Error */
225 \& if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
226 \& /* Error */
227 \&
228 \& /* Perform operation */
229 \& ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen);
230 \&
231 \& /*
232 \& * ret == 1 indicates success, 0 verify failure and < 0 for some
233 \& * other error.
234 \& */
235 .Ve
236 .SS "RSA\-SHA256 with a pre-computed digest"
237 .IX Subsection "RSA-SHA256 with a pre-computed digest"
238 Verify a digest with RSA\-SHA256 using one-shot functions. To be noted is that
239 RSA\-SHA256 is assumed to be an implementation of \f(CW\*(C`sha256WithRSAEncryption\*(C'\fR,
240 for which the padding is pre-determined to be \fBRSA_PKCS1_PADDING\fR, and the
241 input digest is assumed to have been computed using SHA256.
242 .PP
243 .Vb 2
244 \& #include <openssl/evp.h>
245 \& #include <openssl/rsa.h>
246 \&
247 \& EVP_PKEY_CTX *ctx;
248 \& /* md is a SHA\-256 digest in this example. */
249 \& unsigned char *md, *sig;
250 \& size_t mdlen = 32, siglen;
251 \& EVP_PKEY *signing_key;
252 \&
253 \& /*
254 \& * NB: assumes verify_key, sig, siglen, md and mdlen are already set up
255 \& * and that verify_key is an RSA public key
256 \& */
257 \& ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
258 \& alg = EVP_SIGNATURE_fetch(NULL, "RSA\-SHA256", NULL);
259 \&
260 \& if (ctx == NULL)
261 \& /* Error occurred */
262 \& if (EVP_PKEY_verify_init_ex2(ctx, alg, NULL) <= 0)
263 \& /* Error */
264 \&
265 \& /* Determine buffer length */
266 \& if (EVP_PKEY_verify(ctx, sig, siglen, md, mdlen) <= 0)
267 \& /* Error or signature doesn\*(Aqt verify */
268 \&
269 \& /* Perform operation */
270 \& ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen);
271 \&
272 \& /*
273 \& * ret == 1 indicates success, 0 verify failure and < 0 for some
274 \& * other error.
275 \& */
276 .Ve
277 .SS "RSA\-SHA256, one-shot"
278 .IX Subsection "RSA-SHA256, one-shot"
279 Verify a document with RSA\-SHA256 using one-shot functions.
280 To be noted is that RSA\-SHA256 is assumed to be an implementation of
281 \&\f(CW\*(C`sha256WithRSAEncryption\*(C'\fR, for which the padding is pre-determined to be
282 \&\fBRSA_PKCS1_PADDING\fR.
283 .PP
284 .Vb 2
285 \& #include <openssl/evp.h>
286 \& #include <openssl/rsa.h>
287 \&
288 \& EVP_PKEY_CTX *ctx;
289 \& /* in the input in this example. */
290 \& unsigned char *in, *sig;
291 \& /* inlen is the length of the input in this example. */
292 \& size_t inlen, siglen;
293 \& EVP_PKEY *signing_key;
294 \& EVP_SIGNATURE *alg;
295 \&
296 \& /*
297 \& * NB: assumes signing_key, in and inlen are set up before
298 \& * the next step. signing_key must be an RSA private key,
299 \& * in must point to data to be digested and signed, and
300 \& * inlen must be the size of the data in bytes.
301 \& */
302 \& ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
303 \& alg = EVP_SIGNATURE_fetch(NULL, "RSA\-SHA256", NULL);
304 \&
305 \& if (ctx == NULL || alg == NULL)
306 \& /* Error occurred */
307 \& if (EVP_PKEY_verify_message_init(ctx, alg, NULL) <= 0)
308 \& /* Error */
309 \&
310 \& /* Perform operation */
311 \& ret = EVP_PKEY_verify(ctx, sig, siglen, in, inlen);
312 \&
313 \& /*
314 \& * ret == 1 indicates success, 0 verify failure and < 0 for some
315 \& * other error.
316 \& */
317 .Ve
318 .SS "RSA\-SHA256, using update and final"
319 .IX Subsection "RSA-SHA256, using update and final"
320 This is the same as the previous example, but allowing stream-like
321 functionality.
322 .PP
323 .Vb 2
324 \& #include <openssl/evp.h>
325 \& #include <openssl/rsa.h>
326 \&
327 \& EVP_PKEY_CTX *ctx;
328 \& /* in is the input in this example. */
329 \& unsigned char *in, *sig;
330 \& /* inlen is the length of the input in this example. */
331 \& size_t inlen, siglen;
332 \& EVP_PKEY *signing_key;
333 \& EVP_SIGNATURE *alg;
334 \&
335 \& /*
336 \& * NB: assumes signing_key, in and inlen are set up before
337 \& * the next step. signing_key must be an RSA private key,
338 \& * in must point to data to be digested and signed, and
339 \& * inlen must be the size of the data in bytes.
340 \& */
341 \& ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
342 \& alg = EVP_SIGNATURE_fetch(NULL, "RSA\-SHA256", NULL);
343 \&
344 \& if (ctx == NULL || alg == NULL)
345 \& /* Error occurred */
346 \& if (EVP_PKEY_verify_message_init(ctx, alg, NULL) <= 0)
347 \& /* Error */
348 \&
349 \& /* We have the signature, specify it early */
350 \& EVP_PKEY_CTX_set_signature(ctx, sig, siglen);
351 \&
352 \& /* Perform operation */
353 \& while (inlen > 0) {
354 \& if (EVP_PKEY_verify_message_update(ctx, in, inlen)) <= 0)
355 \& /* Error */
356 \& if (inlen > 256) {
357 \& inlen \-= 256;
358 \& in += 256;
359 \& } else {
360 \& inlen = 0;
361 \& }
362 \& }
363 \& ret = EVP_PKEY_verify_message_final(ctx);
364 \&
365 \& /*
366 \& * ret == 1 indicates success, 0 verify failure and < 0 for some
367 \& * other error.
368 \& */
369 .Ve
370 .SH "SEE ALSO"
371 .IX Header "SEE ALSO"
372 \&\fBEVP_PKEY_CTX_new\fR\|(3),
373 \&\fBEVP_PKEY_encrypt\fR\|(3),
374 \&\fBEVP_PKEY_decrypt\fR\|(3),
375 \&\fBEVP_PKEY_sign\fR\|(3),
376 \&\fBEVP_PKEY_verify_recover\fR\|(3),
377 \&\fBEVP_PKEY_derive\fR\|(3)
378 .SH HISTORY
379 .IX Header "HISTORY"
380 The \fBEVP_PKEY_verify_init()\fR and \fBEVP_PKEY_verify()\fR functions were added in
381 OpenSSL 1.0.0.
382 .PP
383 The \fBEVP_PKEY_verify_init_ex()\fR function was added in OpenSSL 3.0.
384 .PP
385 The \fBEVP_PKEY_verify_init_ex2()\fR, \fBEVP_PKEY_verify_message_init()\fR,
386 \&\fBEVP_PKEY_verify_message_update()\fR, \fBEVP_PKEY_verify_message_final()\fR and
387 \&\fBEVP_PKEY_CTX_set_signature()\fR functions where added in OpenSSL 3.4.
388 .SH COPYRIGHT
389 .IX Header "COPYRIGHT"
390 Copyright 2006\-2025 The OpenSSL Project Authors. All Rights Reserved.
391 .PP
392 Licensed under the Apache License 2.0 (the "License"). You may not use
393 this file except in compliance with the License. You can obtain a copy
394 in the file LICENSE in the source distribution or at
395 <https://www.openssl.org/source/license.html>.