jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: EVP_DigestVerifyInit.3,v 1.18 2025/06/08 22:40:29 schwarze Exp $
2.\" full merge up to OpenSSL f097e875 Aug 23 11:37:22 2018 +0100
3.\" selective merge up to 24a535ea Sep 22 13:14:20 2020 +0100
4.\"
5.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
6.\" Copyright (c) 2006, 2009, 2014, 2015, 2016, 2017 The OpenSSL Project.
7.\" All rights reserved.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\"
13.\" 1. Redistributions of source code must retain the above copyright
14.\" notice, this list of conditions and the following disclaimer.
15.\"
16.\" 2. Redistributions in binary form must reproduce the above copyright
17.\" notice, this list of conditions and the following disclaimer in
18.\" the documentation and/or other materials provided with the
19.\" distribution.
20.\"
21.\" 3. All advertising materials mentioning features or use of this
22.\" software must display the following acknowledgment:
23.\" "This product includes software developed by the OpenSSL Project
24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
25.\"
26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
27.\" endorse or promote products derived from this software without
28.\" prior written permission. For written permission, please contact
29.\" openssl-core@openssl.org.
30.\"
31.\" 5. Products derived from this software may not be called "OpenSSL"
32.\" nor may "OpenSSL" appear in their names without prior written
33.\" permission of the OpenSSL Project.
34.\"
35.\" 6. Redistributions of any form whatsoever must retain the following
36.\" acknowledgment:
37.\" "This product includes software developed by the OpenSSL Project
38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
39.\"
40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
51.\" OF THE POSSIBILITY OF SUCH DAMAGE.
52.\"
53.Dd $Mdocdate: June 8 2025 $
54.Dt EVP_DIGESTVERIFYINIT 3
55.Os
56.Sh NAME
57.Nm EVP_DigestVerifyInit ,
58.Nm EVP_DigestVerifyUpdate ,
59.Nm EVP_DigestVerifyFinal ,
60.Nm EVP_DigestVerify
61.Nd EVP signature verification functions
62.Sh SYNOPSIS
63.Lb libcrypto
64.In openssl/evp.h
65.Ft int
66.Fo EVP_DigestVerifyInit
67.Fa "EVP_MD_CTX *ctx"
68.Fa "EVP_PKEY_CTX **pctx"
69.Fa "const EVP_MD *type"
70.Fa "ENGINE *engine"
71.Fa "EVP_PKEY *pkey"
72.Fc
73.Ft int
74.Fo EVP_DigestVerifyUpdate
75.Fa "EVP_MD_CTX *ctx"
76.Fa "const void *d"
77.Fa "size_t cnt"
78.Fc
79.Ft int
80.Fo EVP_DigestVerifyFinal
81.Fa "EVP_MD_CTX *ctx"
82.Fa "const unsigned char *sig"
83.Fa "size_t siglen"
84.Fc
85.Ft int
86.Fo EVP_DigestVerify
87.Fa "EVP_MD_CTX *ctx"
88.Fa "const unsigned char *sig"
89.Fa "size_t siglen"
90.Fa "const unsigned char *tbs"
91.Fa "size_t *tbslen"
92.Fc
93.Sh DESCRIPTION
94The EVP signature routines are a high-level interface to digital
95signatures.
96.Pp
97.Fn EVP_DigestVerifyInit
98sets up the verification context
99.Fa ctx
100to use the digest
101.Fa type
102and the public key
103.Fa pkey .
104Before calling this function, obtain
105.Fa ctx
106from
107.Xr EVP_MD_CTX_new 3
108or call
109.Xr EVP_MD_CTX_reset 3
110on it.
111The
112.Fa engine
113argument is always ignored and passing
114.Dv NULL
115is recommended.
116.Pp
117If
118.Fa pctx
119is not
120.Dv NULL ,
121any pointer passed in as
122.Pf * Fa pctx
123is ignored and overwritten by an internal pointer to the
124.Vt EVP_PKEY_CTX
125used by the verification operation:
126this can be used to set alternative signing options.
127The returned
128.Vt EVP_PKEY_CTX
129must not be freed by the application.
130It is freed automatically when the
131.Vt EVP_MD_CTX
132is freed.
133.Pp
134.Fn EVP_DigestVerifyUpdate
135hashes
136.Fa cnt
137bytes of data at
138.Fa d
139into the verification context
140.Fa ctx .
141This function can be called several times on the same
142.Fa ctx
143to include additional data.
144This function is currently implemented using a macro.
145.Pp
146.Fn EVP_DigestVerifyFinal
147verifies the data in
148.Fa ctx
149against the signature in
150.Fa sig
151of length
152.Fa siglen .
153.Pp
154.Fn EVP_DigestVerify
155verifies
156.Fa tbslen
157bytes at
158.Fa tbs
159against the signature in
160.Fa sig
161of length
162.Fa siglen .
163.Fn EVP_DigestVerify
164is a one shot operation which verifies a single block of data
165in one function call.
166For algorithms that support streaming it is equivalent to calling
167.Fn EVP_DigestVerifyUpdate
168and
169.Fn EVP_DigestVerifyFinal .
170.\" For algorithms which do not support streaming
171.\" (e.g. PureEdDSA)
172.\" it is the only way to verify data.
173.Pp
174The EVP interface to digital signatures should almost always be
175used in preference to the low-level interfaces.
176This is because the code then becomes transparent to the algorithm used
177and much more flexible.
178.Pp
179The call to
180.Fn EVP_DigestVerifyFinal
181internally finalizes a copy of the digest context.
182This means that
183.Xr EVP_VerifyUpdate 3
184and
185.Xr EVP_VerifyFinal 3
186can be called later to digest and verify additional data.
187.Pp
188Since only a copy of the digest context is ever finalized, the context
189must be cleaned up after use by calling
190.Xr EVP_MD_CTX_free 3
191or a memory leak will occur.
192.Sh RETURN VALUES
193.Fn EVP_DigestVerifyInit
194and
195.Fn EVP_DigestVerifyUpdate
196return 1 for success and 0 for failure.
197.Pp
198.Fn EVP_DigestVerifyFinal
199and
200.Fn EVP_DigestVerify
201return 1 for success; any other value indicates failure.
202A return value of 0 indicates that the signature did not verify
203successfully (that is, the signature did not match the original
204data or the signature had an invalid form), while other values
205indicate a more serious error (and sometimes also indicate an invalid
206signature form).
207.Pp
208The error codes can be obtained from
209.Xr ERR_get_error 3 .
210.Sh SEE ALSO
211.Xr evp 3 ,
212.Xr EVP_DigestInit 3 ,
213.Xr EVP_DigestSignInit 3
214.Sh HISTORY
215.Fn EVP_DigestVerifyInit ,
216.Fn EVP_DigestVerifyUpdate ,
217and
218.Fn EVP_DigestVerifyFinal
219first appeared in OpenSSL 1.0.0 and have been available since
220.Ox 4.9 .
221.Pp
222.Fn EVP_DigestVerify
223first appeared in OpenSSL 1.1.1 and has been available since
224.Ox 7.0 .