Debian Codegraph @

upstream/debian-unstable/man3/EVP_PKEY_sign.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_SIGN 3SSL"
58 .TH EVP_PKEY_SIGN 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_sign_init, EVP_PKEY_sign_init_ex, EVP_PKEY_sign_init_ex2,
65 EVP_PKEY_sign, EVP_PKEY_sign_message_init, EVP_PKEY_sign_message_update,
66 EVP_PKEY_sign_message_final \- sign using a public key algorithm
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/evp.h>
71 \&
72 \& int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx);
73 \& int EVP_PKEY_sign_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
74 \& int EVP_PKEY_sign_init_ex2(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo,
75 \& const OSSL_PARAM params[]);
76 \& int EVP_PKEY_sign_message_init(EVP_PKEY_CTX *ctx, EVP_SIGNATURE *algo,
77 \& const OSSL_PARAM params[]);
78 \& int EVP_PKEY_sign_message_update(EVP_PKEY_CTX *ctx,
79 \& unsigned char *in, size_t inlen);
80 \& int EVP_PKEY_sign_message_final(EVP_PKEY_CTX *ctx, unsigned char *sig,
81 \& size_t *siglen, size_t sigsize);
82 \& int EVP_PKEY_sign(EVP_PKEY_CTX *ctx,
83 \& unsigned char *sig, size_t *siglen,
84 \& const unsigned char *tbs, size_t tbslen);
85 .Ve
86 .SH DESCRIPTION
87 .IX Header "DESCRIPTION"
88 \&\fBEVP_PKEY_sign_init()\fR initializes a public key algorithm context \fIctx\fR for
89 signing using the algorithm given when the context was created
90 using \fBEVP_PKEY_CTX_new\fR\|(3) or variants thereof. The algorithm is used to
91 fetch a \fBEVP_SIGNATURE\fR method implicitly, see "Implicit fetch" in \fBprovider\fR\|(7)
92 for more information about implicit fetches.
93 .PP
94 \&\fBEVP_PKEY_sign_init_ex()\fR is the same as \fBEVP_PKEY_sign_init()\fR but additionally
95 sets the passed parameters \fIparams\fR on the context before returning.
96 .PP
97 \&\fBEVP_PKEY_sign_init_ex2()\fR initializes a public key algorithm context \fIctx\fR for
98 signing a pre-computed message digest using the algorithm given by \fIalgo\fR and
99 the key given through \fBEVP_PKEY_CTX_new\fR\|(3) or \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3).
100 A context \fIctx\fR without a pre-loaded key cannot be used with this function.
101 This function provides almost the same functionality as \fBEVP_PKEY_sign_init_ex()\fR,
102 but is uniquely intended to be used with a pre-computed message digest, and
103 allows pre-determining the exact conditions for that message digest, if a
104 composite signature algorithm (such as RSA\-SHA256) was fetched.
105 Following a call to this function, setting parameters that modifies the digest
106 implementation or padding is not normally supported.
107 .PP
108 \&\fBEVP_PKEY_sign_message_init()\fR initializes a public key algorithm context \fIctx\fR
109 for signing an unlimited size message using the algorithm given by \fIalgo\fR and
110 the key given through \fBEVP_PKEY_CTX_new\fR\|(3) or \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3).
111 Passing the message is supported both in a one-shot fashion using
112 \&\fBEVP_PKEY_sign()\fR, and through the combination of \fBEVP_PKEY_sign_message_update()\fR
113 and \fBEVP_PKEY_sign_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_sign_message_update()\fR adds \fIinlen\fR bytes from \fIin\fR to the data to be
118 processed for signature. The signature algorithm specification and
119 implementation determine how the input bytes are processed and if there's a
120 limit on the total size of the input. See "NOTES" below for a deeper
121 explanation.
122 .PP
123 \&\fBEVP_PKEY_sign_message_final()\fR signs the processed data and places the data in
124 \&\fIsig\fR, and the number of signature bytes in \fI*siglen\fR, if the number of
125 bytes doesn't surpass the size given by \fIsigsize\fR.
126 \&\fIsig\fR may be NULL, and in that case, only \fI*siglen\fR is updated with the
127 number of signature bytes.
128 .PP
129 \&\fBEVP_PKEY_sign()\fR is a one-shot function that can be used with all the init
130 functions above.
131 When initialization was done with \fBEVP_PKEY_sign_init()\fR, \fBEVP_PKEY_sign_init_ex()\fR
132 or \fBEVP_PKEY_sign_init_ex2()\fR, the data specified by \fItbs\fR and \fItbslen\fR is
133 signed after appropriate padding.
134 When initialization was done with \fBEVP_PKEY_sign_message_init()\fR, the data
135 specified by \fItbs\fR and \fItbslen\fR is digested by the implied message digest
136 algorithm, and the result is signed after appropriate padding.
137 If \fIsig\fR is NULL then the maximum size of the output buffer is written to the
138 \&\fIsiglen\fR parameter.
139 If \fIsig\fR is not NULL, then before the call the \fIsiglen\fR parameter should
140 contain the length of the \fIsig\fR buffer, and if the call is successful the
141 signature is written to \fIsig\fR and the amount of data written to \fIsiglen\fR.
142 .SH NOTES
143 .IX Header "NOTES"
144 .SS General
145 .IX Subsection "General"
146 Some signature implementations only accumulate the input data and do no
147 further processing before signing it (they expect the input to be a digest),
148 while others compress the data, typically by internally producing a digest,
149 and signing the result.
150 Some of them support both modes of operation at the same time.
151 The caller is expected to know how the chosen algorithm is supposed to behave
152 and under what conditions.
153 .PP
154 For example, an RSA implementation can be expected to only expect a message
155 digest as input, while ED25519 can be expected to process the input with a hash,
156 i.e. to produce the message digest internally, and while RSA\-SHA256 can be
157 expected to handle either mode of operation, depending on if the operation was
158 initialized with \fBEVP_PKEY_sign_init_ex2()\fR or with \fBEVP_PKEY_sign_message_init()\fR.
159 .PP
160 Similarly, an RSA implementation usually expects additional details to be set,
161 like the message digest algorithm that the input is supposed to be digested
162 with, as well as the padding mode (see \fBEVP_PKEY_CTX_set_signature_md\fR\|(3) and
163 \&\fBEVP_PKEY_CTX_set_rsa_padding\fR\|(3) and similar others), while an RSA\-SHA256
164 implementation usually has these details pre-set and immutable.
165 .PP
166 The functions described here can't be used to combine separate algorithms. In
167 particular, neither \fBEVP_PKEY_CTX_set_signature_md\fR\|(3) nor the \fBOSSL_PARAM\fR
168 parameter "digest" (\fBOSSL_SIGNATURE_PARAM_DIGEST\fR) can be used to combine a
169 signature algorithm with a hash algorithm to process the input. In other
170 words, it's not possible to specify a \fIctx\fR pre-loaded with an RSA pkey, or
171 an \fIalgo\fR that fetched \f(CW\*(C`RSA\*(C'\fR and try to specify SHA256 separately to get the
172 functionality of RSA\-SHA256. If combining algorithms in that manner is
173 desired, please use \fBEVP_DigestSignInit\fR\|(3) and associated functions.
174 .SS "Performing multiple signatures"
175 .IX Subsection "Performing multiple signatures"
176 When initialized using \fBEVP_PKEY_sign_init_ex()\fR or \fBEVP_PKEY_sign_init_ex2()\fR,
177 \&\fBEVP_PKEY_sign()\fR can be called more than once on the same context to have
178 several one-shot operations performed using the same parameters.
179 .PP
180 When initialized using \fBEVP_PKEY_sign_message_init()\fR, it's not possible to
181 call \fBEVP_PKEY_sign()\fR multiple times.
182 .SH "RETURN VALUES"
183 .IX Header "RETURN VALUES"
184 All functions return 1 for success and 0 or a negative value for failure.
185 .PP
186 In particular, \fBEVP_PKEY_sign_init()\fR and its other variants may return \-2 to
187 indicate that the operation is not supported by the public key algorithm.
188 .SH EXAMPLES
189 .IX Header "EXAMPLES"
190 .SS "RSA with PKCS#1 padding for SHA256"
191 .IX Subsection "RSA with PKCS#1 padding for SHA256"
192 Sign data using RSA with PKCS#1 padding and a SHA256 digest as input:
193 .PP
194 .Vb 2
195 \& #include <openssl/evp.h>
196 \& #include <openssl/rsa.h>
197 \&
198 \& EVP_PKEY_CTX *ctx;
199 \& /* md is a SHA\-256 digest in this example. */
200 \& unsigned char *md, *sig;
201 \& size_t mdlen = 32, siglen;
202 \& EVP_PKEY *signing_key;
203 \&
204 \& /*
205 \& * NB: assumes signing_key and md are set up before the next
206 \& * step. signing_key must be an RSA private key and md must
207 \& * point to the SHA\-256 digest to be signed.
208 \& */
209 \& ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
210 \& if (ctx == NULL)
211 \& /* Error occurred */
212 \& if (EVP_PKEY_sign_init(ctx) <= 0)
213 \& /* Error */
214 \& if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
215 \& /* Error */
216 \& if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
217 \& /* Error */
218 \&
219 \& /* Determine buffer length */
220 \& if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0)
221 \& /* Error */
222 \&
223 \& sig = OPENSSL_malloc(siglen);
224 \&
225 \& if (sig == NULL)
226 \& /* malloc failure */
227 \&
228 \& if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0)
229 \& /* Error */
230 \&
231 \& /* Signature is siglen bytes written to buffer sig */
232 .Ve
233 .SS "RSA\-SHA256 with a pre-computed digest"
234 .IX Subsection "RSA-SHA256 with a pre-computed digest"
235 Sign a digest with RSA\-SHA256 using one-shot functions. To be noted is that
236 RSA\-SHA256 is assumed to be an implementation of \f(CW\*(C`sha256WithRSAEncryption\*(C'\fR,
237 for which the padding is pre-determined to be \fBRSA_PKCS1_PADDING\fR, and the
238 input digest is assumed to have been computed using SHA256.
239 .PP
240 .Vb 2
241 \& #include <openssl/evp.h>
242 \& #include <openssl/rsa.h>
243 \&
244 \& EVP_PKEY_CTX *ctx;
245 \& /* md is a SHA\-256 digest in this example. */
246 \& unsigned char *md, *sig;
247 \& size_t mdlen = 32, siglen;
248 \& EVP_PKEY *signing_key;
249 \&
250 \& /*
251 \& * NB: assumes signing_key and md are set up before the next
252 \& * step. signing_key must be an RSA private key and md must
253 \& * point to the SHA\-256 digest to be signed.
254 \& */
255 \& ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
256 \& alg = EVP_SIGNATURE_fetch(NULL, "RSA\-SHA256", NULL);
257 \&
258 \& if (ctx == NULL)
259 \& /* Error occurred */
260 \& if (EVP_PKEY_sign_init_ex2(ctx, alg, NULL) <= 0)
261 \& /* Error */
262 \&
263 \& /* Determine buffer length */
264 \& if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0)
265 \& /* Error */
266 \&
267 \& sig = OPENSSL_malloc(siglen);
268 \&
269 \& if (sig == NULL)
270 \& /* malloc failure */
271 \&
272 \& if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0)
273 \& /* Error */
274 \&
275 \& /* Signature is siglen bytes written to buffer sig */
276 .Ve
277 .SS "RSA\-SHA256, one-shot"
278 .IX Subsection "RSA-SHA256, one-shot"
279 Sign 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 is 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_sign_message_init(ctx, alg, NULL) <= 0)
308 \& /* Error */
309 \&
310 \& /* Determine sig buffer length */
311 \& if (EVP_PKEY_sign(ctx, NULL, &siglen, in, inlen) <= 0)
312 \& /* Error */
313 \&
314 \& sig = OPENSSL_malloc(siglen);
315 \&
316 \& if (sig == NULL)
317 \& /* malloc failure */
318 \&
319 \& if (EVP_PKEY_sign(ctx, sig, &siglen, in, inlen) <= 0)
320 \& /* Error */
321 \&
322 \& /* Signature is siglen bytes written to buffer sig */
323 .Ve
324 .SS "RSA\-SHA256, using update and final"
325 .IX Subsection "RSA-SHA256, using update and final"
326 This is the same as the previous example, but allowing stream-like
327 functionality.
328 .PP
329 .Vb 2
330 \& #include <openssl/evp.h>
331 \& #include <openssl/rsa.h>
332 \&
333 \& EVP_PKEY_CTX *ctx;
334 \& /* in is the input in this example. */
335 \& unsigned char *in, *sig;
336 \& /* inlen is the length of the input in this example. */
337 \& size_t inlen, siglen;
338 \& EVP_PKEY *signing_key;
339 \& EVP_SIGNATURE *alg;
340 \&
341 \& /*
342 \& * NB: assumes signing_key, in and inlen are set up before
343 \& * the next step. signing_key must be an RSA private key,
344 \& * in must point to data to be digested and signed, and
345 \& * inlen must be the size of the data in bytes.
346 \& */
347 \& ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
348 \& alg = EVP_SIGNATURE_fetch(NULL, "RSA\-SHA256", NULL);
349 \&
350 \& if (ctx == NULL || alg == NULL)
351 \& /* Error occurred */
352 \& if (EVP_PKEY_sign_message_init(ctx, alg, NULL) <= 0)
353 \& /* Error */
354 \&
355 \& while (inlen > 0) {
356 \& if (EVP_PKEY_sign_message_update(ctx, in, inlen)) <= 0)
357 \& /* Error */
358 \& if (inlen > 256) {
359 \& inlen \-= 256;
360 \& in += 256;
361 \& } else {
362 \& inlen = 0;
363 \& }
364 \& }
365 \&
366 \& /* Determine sig buffer length */
367 \& if (EVP_PKEY_sign_message_final(ctx, NULL, &siglen) <= 0)
368 \& /* Error */
369 \&
370 \& sig = OPENSSL_malloc(siglen);
371 \&
372 \& if (sig == NULL)
373 \& /* malloc failure */
374 \&
375 \& if (EVP_PKEY_sign_message_final(ctx, sig, &siglen) <= 0)
376 \& /* Error */
377 \&
378 \& /* Signature is siglen bytes written to buffer sig */
379 .Ve
380 .SH "SEE ALSO"
381 .IX Header "SEE ALSO"
382 \&\fBEVP_PKEY_CTX_new\fR\|(3),
383 \&\fBEVP_PKEY_CTX_ctrl\fR\|(3),
384 \&\fBEVP_PKEY_encrypt\fR\|(3),
385 \&\fBEVP_PKEY_decrypt\fR\|(3),
386 \&\fBEVP_PKEY_verify\fR\|(3),
387 \&\fBEVP_PKEY_verify_recover\fR\|(3),
388 \&\fBEVP_PKEY_derive\fR\|(3)
389 .SH HISTORY
390 .IX Header "HISTORY"
391 The \fBEVP_PKEY_sign_init()\fR and \fBEVP_PKEY_sign()\fR functions were added in
392 OpenSSL 1.0.0.
393 .PP
394 The \fBEVP_PKEY_sign_init_ex()\fR function was added in OpenSSL 3.0.
395 .PP
396 The \fBEVP_PKEY_sign_init_ex2()\fR, \fBEVP_PKEY_sign_message_init()\fR,
397 \&\fBEVP_PKEY_sign_message_update()\fR and \fBEVP_PKEY_sign_message_final()\fR functions
398 where added in OpenSSL 3.4.
399 .SH COPYRIGHT
400 .IX Header "COPYRIGHT"
401 Copyright 2006\-2025 The OpenSSL Project Authors. All Rights Reserved.
402 .PP
403 Licensed under the Apache License 2.0 (the "License"). You may not use
404 this file except in compliance with the License. You can obtain a copy
405 in the file LICENSE in the source distribution or at
406 <https://www.openssl.org/source/license.html>.