jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: EVP_DigestSignInit.3,v 1.16 2025/06/08 22:40:29 schwarze Exp $
2.\" full merge up to: OpenSSL 28428130 Apr 17 15:18:40 2018 +0200
3.\" selective merge up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200
4.\"
5.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
6.\" Copyright (c) 2006, 2009, 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_DIGESTSIGNINIT 3
55.Os
56.Sh NAME
57.Nm EVP_DigestSignInit ,
58.Nm EVP_DigestSignUpdate ,
59.Nm EVP_DigestSignFinal ,
60.Nm EVP_DigestSign
61.Nd EVP signing functions
62.Sh SYNOPSIS
63.Lb libcrypto
64.In openssl/evp.h
65.Ft int
66.Fo EVP_DigestSignInit
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_DigestSignUpdate
75.Fa "EVP_MD_CTX *ctx"
76.Fa "const void *d"
77.Fa "size_t cnt"
78.Fc
79.Ft int
80.Fo EVP_DigestSignFinal
81.Fa "EVP_MD_CTX *ctx"
82.Fa "unsigned char *sig"
83.Fa "size_t *siglen"
84.Fc
85.Ft int
86.Fo EVP_DigestSign
87.Fa "EVP_MD_CTX *ctx"
88.Fa "unsigned char *sigret"
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_DigestSignInit
98sets up the signing context
99.Fa ctx
100to use the digest
101.Fa type
102and the private 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 signing 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_DigestSignUpdate
135hashes
136.Fa cnt
137bytes of data at
138.Fa d
139into the signature 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_DigestSignFinal
147signs the data in
148.Fa ctx
149and places the signature in
150.Fa sig .
151If
152.Fa sig
153is
154.Dv NULL ,
155then the maximum size of the output buffer is written to
156.Pf * Fa siglen .
157If
158.Fa sig
159is not
160.Dv NULL ,
161then before the call
162.Fa siglen
163should contain the length of the
164.Fa sig
165buffer.
166If the call is successful, the signature is written to
167.Fa sig
168and the amount of data written to
169.Fa siglen .
170.Pp
171.Fn EVP_DigestSign
172signs
173.Fa tbslen
174bytes of data at
175.Fa tbs
176and places the signature in
177.Fa sigret
178and its length in
179.Fa siglen
180in a similar way to
181.Fn EVP_DigestSignFinal .
182.Fn EVP_DigestSign
183is a one shot operation which signs a single block of data
184with one function call.
185For algorithms that support streaming it is equivalent to calling
186.Fn EVP_DigestSignUpdate
187and
188.Fn EVP_DigestSignFinal .
189.\" For algorithms which do not support streaming
190.\" (e.g. PureEdDSA)
191.\" it is the only way to sign data.
192.Pp
193The EVP interface to digital signatures should almost always be
194used in preference to the low-level interfaces.
195This is because the code then becomes transparent to the algorithm used
196and much more flexible.
197.Pp
198The call to
199.Fn EVP_DigestSignFinal
200internally finalizes a copy of the digest context.
201This means that
202.Fn EVP_DigestSignUpdate
203and
204.Fn EVP_DigestSignFinal
205can be called later to digest and sign additional data.
206.Pp
207Since only a copy of the digest context is ever finalized, the context
208must be cleaned up after use by calling
209.Xr EVP_MD_CTX_free 3 ,
210or a memory leak will occur.
211.Pp
212The use of
213.Xr EVP_PKEY_size 3
214with these functions is discouraged because some signature operations
215may have a signature length which depends on the parameters set.
216As a result,
217.Xr EVP_PKEY_size 3
218would have to return a value which indicates the maximum possible
219signature for any set of parameters.
220.Sh RETURN VALUES
221.Fn EVP_DigestSignInit ,
222.Fn EVP_DigestSignUpdate ,
223.Fn EVP_DigestSignFinal ,
224and
225.Fn EVP_DigestSign
226return 1 for success and 0 for failure.
227.Pp
228The error codes can be obtained from
229.Xr ERR_get_error 3 .
230.Sh SEE ALSO
231.Xr evp 3 ,
232.Xr EVP_DigestInit 3 ,
233.Xr EVP_DigestVerifyInit 3
234.Sh HISTORY
235.Fn EVP_DigestSignInit ,
236.Fn EVP_DigestSignUpdate ,
237and
238.Fn EVP_DigestSignFinal
239first appeared in OpenSSL 1.0.0 and have been available since
240.Ox 4.9 .
241.Pp
242.Fn EVP_DigestSign
243first appeared in OpenSSL 1.1.1 and has been available since
244.Ox 7.0 .