Debian Codegraph @

upstream/debian-unstable/man3/EVP_SignInit.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_SIGNINIT 3SSL"
58 .TH EVP_SIGNINIT 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_SignInit, EVP_SignInit_ex, EVP_SignUpdate,
65 EVP_SignFinal_ex, EVP_SignFinal
66 \&\- EVP signing functions
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/evp.h>
71 \&
72 \& int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
73 \& int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
74 \& int EVP_SignFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s,
75 \& EVP_PKEY *pkey, OSSL_LIB_CTX *libctx, const char *propq);
76 \& int EVP_SignFinal(EVP_MD_CTX *ctx, unsigned char *sig, unsigned int *s,
77 \& EVP_PKEY *pkey);
78 \&
79 \& void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
80 .Ve
81 .SH DESCRIPTION
82 .IX Header "DESCRIPTION"
83 The EVP signature routines are a high-level interface to digital
84 signatures.
85 .PP
86 \&\fBEVP_SignInit_ex()\fR sets up signing context \fIctx\fR to use digest
87 \&\fItype\fR from \fBENGINE\fR \fIimpl\fR. \fIctx\fR must be created with
88 \&\fBEVP_MD_CTX_new()\fR before calling this function.
89 .PP
90 \&\fBEVP_SignUpdate()\fR hashes \fIcnt\fR bytes of data at \fId\fR into the
91 signature context \fIctx\fR. This function can be called several times on the
92 same \fIctx\fR to include additional data.
93 .PP
94 \&\fBEVP_SignFinal_ex()\fR signs the data in \fIctx\fR using the private key
95 \&\fIpkey\fR and places the signature in \fIsig\fR. The library context \fIlibctx\fR and
96 property query \fIpropq\fR are used when creating a context to use with the key
97 \&\fIpkey\fR. \fIsig\fR must be at least \f(CWEVP_PKEY_get_size(pkey)\fR bytes in size.
98 \&\fIs\fR is an OUT parameter, and not used as an IN parameter.
99 The number of bytes of data written (i.e. the length of the signature)
100 will be written to the integer at \fIs\fR, at most \f(CWEVP_PKEY_get_size(pkey)\fR
101 bytes will be written.
102 .PP
103 \&\fBEVP_SignFinal()\fR is similar to \fBEVP_SignFinal_ex()\fR but uses default
104 values of NULL for the library context \fIlibctx\fR and the property query \fIpropq\fR.
105 .PP
106 \&\fBEVP_SignInit()\fR initializes a signing context \fIctx\fR to use the default
107 implementation of digest \fItype\fR.
108 .SH "RETURN VALUES"
109 .IX Header "RETURN VALUES"
110 \&\fBEVP_SignInit_ex()\fR, \fBEVP_SignUpdate()\fR, \fBEVP_SignFinal_ex()\fR and
111 \&\fBEVP_SignFinal()\fR return 1 for success and 0 for failure.
112 .PP
113 The error codes can be obtained by \fBERR_get_error\fR\|(3).
114 .SH NOTES
115 .IX Header "NOTES"
116 The \fBEVP\fR interface to digital signatures should almost always be used in
117 preference to the low-level interfaces. This is because the code then becomes
118 transparent to the algorithm used and much more flexible.
119 .PP
120 When signing with some private key types the random number generator must
121 be seeded. If the automatic seeding or reseeding of the OpenSSL CSPRNG fails
122 due to external circumstances (see \fBRAND\fR\|(7)), the operation will fail.
123 .PP
124 The call to \fBEVP_SignFinal()\fR internally finalizes a copy of the digest context.
125 This means that calls to \fBEVP_SignUpdate()\fR and \fBEVP_SignFinal()\fR can be called
126 later to digest and sign additional data.cApplications may disable this
127 behavior by setting the EVP_MD_CTX_FLAG_FINALISE context flag via
128 \&\fBEVP_MD_CTX_set_flags\fR\|(3).
129 .PP
130 Since only a copy of the digest context is ever finalized the context must
131 be cleaned up after use by calling \fBEVP_MD_CTX_free()\fR or a memory leak
132 will occur.
133 .PP
134 Note that not all providers support continuation, in case the selected
135 provider does not allow to duplicate contexts \fBEVP_SignFinal()\fR will
136 finalize the digest context and attempting to process additional data via
137 \&\fBEVP_SignUpdate()\fR will result in an error.
138 .SH BUGS
139 .IX Header "BUGS"
140 Older versions of this documentation wrongly stated that calls to
141 \&\fBEVP_SignUpdate()\fR could not be made after calling \fBEVP_SignFinal()\fR.
142 .PP
143 Since the private key is passed in the call to \fBEVP_SignFinal()\fR any error
144 relating to the private key (for example an unsuitable key and digest
145 combination) will not be indicated until after potentially large amounts of
146 data have been passed through \fBEVP_SignUpdate()\fR.
147 .PP
148 It is not possible to change the signing parameters using these function.
149 .PP
150 The previous two bugs are fixed in the newer EVP_DigestSign*() functions.
151 .SH "SEE ALSO"
152 .IX Header "SEE ALSO"
153 \&\fBEVP_PKEY_get_size\fR\|(3), \fBEVP_PKEY_get_bits\fR\|(3),
154 \&\fBEVP_PKEY_get_security_bits\fR\|(3),
155 \&\fBEVP_VerifyInit\fR\|(3),
156 \&\fBEVP_DigestInit\fR\|(3),
157 \&\fBevp\fR\|(7), \fBHMAC\fR\|(3), \fBMD2\fR\|(3),
158 \&\fBMD5\fR\|(3), \fBMDC2\fR\|(3), \fBRIPEMD160\fR\|(3),
159 \&\fBSHA1\fR\|(3), \fBopenssl\-dgst\fR\|(1)
160 .SH HISTORY
161 .IX Header "HISTORY"
162 The function \fBEVP_SignFinal_ex()\fR was added in OpenSSL 3.0.
163 .SH COPYRIGHT
164 .IX Header "COPYRIGHT"
165 Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
166 .PP
167 Licensed under the Apache License 2.0 (the "License"). You may not use
168 this file except in compliance with the License. You can obtain a copy
169 in the file LICENSE in the source distribution or at
170 <https://www.openssl.org/source/license.html>.