Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / EVP_SignInit.3
1 .rn '' }`
2 ''' $RCSfile$$Revision$$Date$
3 '''
4 ''' $Log$
5 '''
6 .de Sh
7 .br
8 .if t .Sp
9 .ne 5
10 .PP
11 \fB\\$1\fR
12 .PP
13 ..
14 .de Sp
15 .if t .sp .5v
16 .if n .sp
17 ..
18 .de Ip
19 .br
20 .ie \\n(.$>=3 .ne \\$3
21 .el .ne 3
22 .IP "\\$1" \\$2
23 ..
24 .de Vb
25 .ft CW
26 .nf
27 .ne \\$1
28 ..
29 .de Ve
30 .ft R
31
32 .fi
33 ..
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 '''
40 .tr \(*W-|\(bv\*(Tr
41 .ie n \{\
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' '
62 'br\}
63 .el\{\
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
79 'br\}
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"
92 ..
93 .nr % 0
94 .rr F
95 .\}
96 .TH EVP_SignInit 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97 .UC
98 .if n .hy 0
99 .if n .na
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
112 .bd B 3
113 .       \" fudge factors for nroff and troff
114 .if n \{\
115 .       ds #H 0
116 .       ds #V .8m
117 .       ds #F .3m
118 .       ds #[ \f1
119 .       ds #] \fP
120 .\}
121 .if t \{\
122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123 .       ds #V .6m
124 .       ds #F 0
125 .       ds #[ \&
126 .       ds #] \&
127 .\}
128 .       \" simple accents for nroff and troff
129 .if n \{\
130 .       ds ' \&
131 .       ds ` \&
132 .       ds ^ \&
133 .       ds , \&
134 .       ds ~ ~
135 .       ds ? ?
136 .       ds ! !
137 .       ds /
138 .       ds q
139 .\}
140 .if t \{\
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'
150 .\}
151 .       \" troff and (daisy-wheel) nroff accents
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'
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'\*(#]
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
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
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'
170 .       \" for low resolution devices (crt and lpr)
171 .if \n(.H>23 .if \n(.V>19 \
172 \{\
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
188 .\}
189 .rm #[ #] #H #V #F C
190 .SH "NAME"
191 EVP_SignInit, EVP_SignUpdate, EVP_SignFinal \- EVP signing functions
192 .SH "SYNOPSIS"
193 .PP
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"
209 The EVP signature routines are a high level interface to digital
210 signatures.
211 .PP
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.
215 .PP
216 \fIEVP_SignUpdate()\fR hashes \fBcnt\fR bytes of data at \fBd\fR into the
217 signature context \fBctx\fR. This function can be called several times on the
218 same \fBctx\fR to include additional data.
219 .PP
220 \fIEVP_SignFinal()\fR signs the data in \fBctx\fR using the private key \fBpkey\fR
221 and places the signature in \fBsig\fR. If the \fBs\fR parameter is not NULL
222 then the number of bytes of data written (i.e. the length of the signature)
223 will be written to the integer at \fBs\fR, at most \fIEVP_PKEY_size\fR\|(pkey) bytes
224 will be written. 
225 .PP
226 \fIEVP_SignInit()\fR initializes a signing context \fBctx\fR to use the default
227 implementation of digest \fBtype\fR.
228 .PP
229 \fIEVP_PKEY_size()\fR returns the maximum size of a signature in bytes. The actual
230 signature returned by \fIEVP_SignFinal()\fR may be smaller.
231 .SH "RETURN VALUES"
232 \fIEVP_SignInit_ex()\fR, \fIEVP_SignUpdate()\fR and \fIEVP_SignFinal()\fR return 1
233 for success and 0 for failure.
234 .PP
235 \fIEVP_PKEY_size()\fR returns the maximum size of a signature in bytes.
236 .PP
237 The error codes can be obtained by ERR_get_error(3).
238 .SH "NOTES"
239 The \fBEVP\fR interface to digital signatures should almost always be used in
240 preference to the low level interfaces. This is because the code then becomes
241 transparent to the algorithm used and much more flexible.
242 .PP
243 Due to the link between message digests and public key algorithms the correct
244 digest algorithm must be used with the correct public key type. A list of
245 algorithms and associated public key algorithms appears in 
246 EVP_DigestInit(3).
247 .PP
248 When signing with DSA private keys the random number generator must be seeded
249 or the operation will fail. The random number generator does not need to be
250 seeded for RSA signatures.
251 .PP
252 The call to \fIEVP_SignFinal()\fR internally finalizes a copy of the digest context.
253 This means that calls to \fIEVP_SignUpdate()\fR and \fIEVP_SignFinal()\fR can be called
254 later to digest and sign additional data.
255 .PP
256 Since only a copy of the digest context is ever finalized the context must
257 be cleaned up after use by calling \fIEVP_MD_CTX_cleanup()\fR or a memory leak
258 will occur.
259 .SH "BUGS"
260 Older versions of this documentation wrongly stated that calls to 
261 \fIEVP_SignUpdate()\fR could not be made after calling \fIEVP_SignFinal()\fR.
262 .SH "SEE ALSO"
263 EVP_VerifyInit(3),
264 EVP_DigestInit(3), err(3),
265 evp(3), hmac(3), md2(3),
266 md5(3), mdc2(3), ripemd(3),
267 sha(3), dgst(1)
268 .SH "HISTORY"
269 \fIEVP_SignInit()\fR, \fIEVP_SignUpdate()\fR and \fIEVP_SignFinal()\fR are
270 available in all versions of SSLeay and OpenSSL.
271 .PP
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