Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / EVP_SignInit.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH EVP_SignInit 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc 190.SH "NAME"
74dab6c2 191EVP_SignInit, EVP_SignUpdate, EVP_SignFinal \- EVP signing functions
984263bc 192.SH "SYNOPSIS"
74dab6c2 193.PP
984263bc
MD
194.Vb 1
195\& #include <openssl/evp.h>
196.Ve
197.Vb 3
198\& int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
199\& int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
200\& int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey);
201.Ve
202.Vb 1
203\& void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
204.Ve
205.Vb 1
206\& int EVP_PKEY_size(EVP_PKEY *pkey);
207.Ve
208.SH "DESCRIPTION"
74dab6c2 209The EVP signature routines are a high level interface to digital
984263bc
MD
210signatures.
211.PP
74dab6c2
JR
212\fIEVP_SignInit_ex()\fR sets up signing context \fBctx\fR to use digest
213\fBtype\fR from ENGINE \fBimpl\fR. \fBctx\fR must be initialized with
214\fIEVP_MD_CTX_init()\fR before calling this function.
984263bc 215.PP
74dab6c2 216\fIEVP_SignUpdate()\fR hashes \fBcnt\fR bytes of data at \fBd\fR into the
984263bc
MD
217signature context \fBctx\fR. This function can be called several times on the
218same \fBctx\fR to include additional data.
219.PP
74dab6c2
JR
220\fIEVP_SignFinal()\fR signs the data in \fBctx\fR using the private key \fBpkey\fR
221and places the signature in \fBsig\fR. If the \fBs\fR parameter is not NULL
984263bc 222then the number of bytes of data written (i.e. the length of the signature)
74dab6c2 223will be written to the integer at \fBs\fR, at most \fIEVP_PKEY_size\fR\|(pkey) bytes
984263bc
MD
224will be written.
225.PP
74dab6c2 226\fIEVP_SignInit()\fR initializes a signing context \fBctx\fR to use the default
984263bc
MD
227implementation of digest \fBtype\fR.
228.PP
74dab6c2 229\fIEVP_PKEY_size()\fR returns the maximum size of a signature in bytes. The actual
984263bc
MD
230signature returned by \fIEVP_SignFinal()\fR may be smaller.
231.SH "RETURN VALUES"
74dab6c2 232\fIEVP_SignInit_ex()\fR, \fIEVP_SignUpdate()\fR and \fIEVP_SignFinal()\fR return 1
984263bc
MD
233for success and 0 for failure.
234.PP
74dab6c2 235\fIEVP_PKEY_size()\fR returns the maximum size of a signature in bytes.
984263bc
MD
236.PP
237The error codes can be obtained by ERR_get_error(3).
238.SH "NOTES"
74dab6c2 239The \fBEVP\fR interface to digital signatures should almost always be used in
984263bc
MD
240preference to the low level interfaces. This is because the code then becomes
241transparent to the algorithm used and much more flexible.
242.PP
243Due to the link between message digests and public key algorithms the correct
244digest algorithm must be used with the correct public key type. A list of
245algorithms and associated public key algorithms appears in
246EVP_DigestInit(3).
247.PP
74dab6c2 248When signing with DSA private keys the random number generator must be seeded
984263bc 249or the operation will fail. The random number generator does not need to be
74dab6c2 250seeded for RSA signatures.
984263bc
MD
251.PP
252The call to \fIEVP_SignFinal()\fR internally finalizes a copy of the digest context.
253This means that calls to \fIEVP_SignUpdate()\fR and \fIEVP_SignFinal()\fR can be called
254later to digest and sign additional data.
255.PP
256Since only a copy of the digest context is ever finalized the context must
257be cleaned up after use by calling \fIEVP_MD_CTX_cleanup()\fR or a memory leak
258will occur.
259.SH "BUGS"
984263bc 260Older versions of this documentation wrongly stated that calls to
74dab6c2 261\fIEVP_SignUpdate()\fR could not be made after calling \fIEVP_SignFinal()\fR.
984263bc 262.SH "SEE ALSO"
984263bc
MD
263EVP_VerifyInit(3),
264EVP_DigestInit(3), err(3),
265evp(3), hmac(3), md2(3),
266md5(3), mdc2(3), ripemd(3),
267sha(3), dgst(1)
268.SH "HISTORY"
74dab6c2 269\fIEVP_SignInit()\fR, \fIEVP_SignUpdate()\fR and \fIEVP_SignFinal()\fR are
984263bc
MD
270available in all versions of SSLeay and OpenSSL.
271.PP
74dab6c2
JR
272\fIEVP_SignInit_ex()\fR was added in OpenSSL 0.9.7.
273
274.rn }` ''
275.IX Title "EVP_SignInit 3"
276.IX Name "EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions"
277
278.IX Header "NAME"
279
280.IX Header "SYNOPSIS"
281
282.IX Header "DESCRIPTION"
283
284.IX Header "RETURN VALUES"
285
286.IX Header "NOTES"
287
288.IX Header "BUGS"
289
290.IX Header "SEE ALSO"
291
292.IX Header "HISTORY"
293