| blob | da3d3fe0d105b9828830157cf08889e1ea07e3cc |
1 .\" $OpenBSD: ECDSA_SIG_new.3,v 1.8 2017/01/06 20:35:23 schwarze Exp $
2 .\" OpenSSL e6390aca Jul 21 10:06:03 2015 -0400
3 .\"
4 .\" This file was written by Nils Larsch <nils@openssl.org>.
5 .\" Copyright (c) 2004, 2005, 2012, 2013 The OpenSSL Project.
6 .\" All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\"
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in
17 .\" the documentation and/or other materials provided with the
18 .\" distribution.
19 .\"
20 .\" 3. All advertising materials mentioning features or use of this
21 .\" software must display the following acknowledgment:
22 .\" "This product includes software developed by the OpenSSL Project
23 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\" endorse or promote products derived from this software without
27 .\" prior written permission. For written permission, please contact
28 .\" openssl-core@openssl.org.
29 .\"
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\" nor may "OpenSSL" appear in their names without prior written
32 .\" permission of the OpenSSL Project.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" acknowledgment:
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .\"
52 .Dd $Mdocdate: January 6 2017 $
53 .Dt ECDSA_SIG_NEW 3
54 .Os
55 .Sh NAME
56 .Nm ECDSA_SIG_new ,
57 .Nm ECDSA_SIG_free ,
58 .Nm i2d_ECDSA_SIG ,
59 .Nm d2i_ECDSA_SIG ,
60 .Nm ECDSA_size ,
61 .Nm ECDSA_sign_setup ,
62 .Nm ECDSA_sign ,
63 .Nm ECDSA_sign_ex ,
64 .Nm ECDSA_verify ,
65 .Nm ECDSA_do_sign ,
66 .Nm ECDSA_do_sign_ex ,
67 .Nm ECDSA_do_verify ,
68 .Nm ECDSA_OpenSSL ,
69 .Nm ECDSA_get_default_method ,
70 .Nm ECDSA_set_default_method ,
71 .Nm ECDSA_set_method
72 .Nd Elliptic Curve Digital Signature Algorithm
73 .Sh SYNOPSIS
74 .In openssl/ecdsa.h
75 .Ft ECDSA_SIG*
76 .Fo ECDSA_SIG_new
77 .Fa void
78 .Fc
79 .Ft void
80 .Fo ECDSA_SIG_free
81 .Fa "ECDSA_SIG *sig"
82 .Fc
83 .Ft int
84 .Fo i2d_ECDSA_SIG
85 .Fa "const ECDSA_SIG *sig"
86 .Fa "unsigned char **pp"
87 .Fc
88 .Ft ECDSA_SIG*
89 .Fo d2i_ECDSA_SIG
90 .Fa "ECDSA_SIG **sig"
91 .Fa "const unsigned char **pp"
92 .Fa "long len"
93 .Fc
94 .Ft int
95 .Fo ECDSA_size
96 .Fa "const EC_KEY *eckey"
97 .Fc
98 .Ft int
99 .Fo ECDSA_sign_setup
100 .Fa "EC_KEY *eckey"
101 .Fa "BN_CTX *ctx"
102 .Fa "BIGNUM **kinv"
103 .Fa "BIGNUM **rp"
104 .Fc
105 .Ft int
106 .Fo ECDSA_sign
107 .Fa "int type"
108 .Fa "const unsigned char *dgst"
109 .Fa "int dgstlen"
110 .Fa "unsigned char *sig"
111 .Fa "unsigned int *siglen"
112 .Fa "EC_KEY *eckey"
113 .Fc
114 .Ft int
115 .Fo ECDSA_sign_ex
116 .Fa "int type"
117 .Fa "const unsigned char *dgst"
118 .Fa "int dgstlen"
119 .Fa "unsigned char *sig"
120 .Fa "unsigned int *siglen"
121 .Fa "const BIGNUM *kinv"
122 .Fa "const BIGNUM *rp"
123 .Fa "EC_KEY *eckey"
124 .Fc
125 .Ft int
126 .Fo ECDSA_verify
127 .Fa "int type"
128 .Fa "const unsigned char *dgst"
129 .Fa "int dgstlen"
130 .Fa "const unsigned char *sig"
131 .Fa "int siglen"
132 .Fa "EC_KEY *eckey"
133 .Fc
134 .Ft ECDSA_SIG*
135 .Fo ECDSA_do_sign
136 .Fa "const unsigned char *dgst"
137 .Fa "int dgst_len"
138 .Fa "EC_KEY *eckey"
139 .Fc
140 .Ft ECDSA_SIG*
141 .Fo ECDSA_do_sign_ex
142 .Fa "const unsigned char *dgst"
143 .Fa "int dgstlen"
144 .Fa "const BIGNUM *kinv"
145 .Fa "const BIGNUM *rp"
146 .Fa "EC_KEY *eckey"
147 .Fc
148 .Ft int
149 .Fo ECDSA_do_verify
150 .Fa "const unsigned char *dgst"
151 .Fa "int dgst_len"
152 .Fa "const ECDSA_SIG *sig"
153 .Fa "EC_KEY* eckey"
154 .Fc
155 .Ft const ECDSA_METHOD*
156 .Fo ECDSA_OpenSSL
157 .Fa void
158 .Fc
159 .Ft const ECDSA_METHOD*
160 .Fo ECDSA_get_default_method
161 .Fa void
162 .Fc
163 .Ft void
164 .Fo ECDSA_set_default_method
165 .Fa "const ECDSA_METHOD *meth"
166 .Fc
167 .Ft int
168 .Fo ECDSA_set_method
169 .Fa "EC_KEY *eckey"
170 .Fa "const ECDSA_METHOD *meth"
171 .Fc
172 .Sh DESCRIPTION
173 These functions provide a low level interface to ECDSA.
174 Most applications should use the higher level EVP interface such as
175 .Xr EVP_DigestSignInit 3
176 or
177 .Xr EVP_DigestVerifyInit 3
178 instead.
179 Creation of the required
180 .Vt EC_KEY
181 objects is described in
182 .Xr EC_KEY_new 3 .
183 .Pp
184 The
185 .Vt ECDSA_SIG
186 structure consists of two
187 .Vt BIGNUM Ns s
188 for the
189 .Fa r
190 and
191 .Fa s
192 value of an ECDSA signature (see X9.62 or FIPS 186-2).
193 .Bd -literal -offset indent
194 struct {
195 BIGNUM *r;
196 BIGNUM *s;
197 } ECDSA_SIG;
198 .Ed
199 .Pp
200 .Fn ECDSA_SIG_new
201 allocates a new
202 .Vt ECDSA_SIG
203 structure (note: this function also allocates the
204 .Vt BIGNUM Ns s )
205 and initializes it.
206 .Pp
207 .Fn ECDSA_SIG_free
208 frees the
209 .Vt ECDSA_SIG
210 structure
211 .Fa sig .
212 .Pp
213 .Fn i2d_ECDSA_SIG
214 creates the DER encoding of the ECDSA signature
215 .Fa sig
216 and writes the encoded signature to
217 .Fa *pp
218 (note: if
219 .Fa pp
220 is
221 .Dv NULL ,
222 .Fn i2d_ECDSA_SIG
223 returns the expected length in bytes of the DER-encoded signature).
224 .Fn i2d_ECDSA_SIG
225 returns the length of the DER-encoded signature (or 0 on error).
226 .Pp
227 .Fn d2i_ECDSA_SIG
228 decodes a DER-encoded ECDSA signature and returns the decoded signature
229 in a newly allocated
230 .Vt ECDSA_SIG
231 structure.
232 .Fa *sig
233 points to the buffer containing the DER-encoded signature of size
234 .Fa len .
235 .Pp
236 .Fn ECDSA_size
237 returns the maximum length of a DER-encoded ECDSA signature created with
238 the private EC key
239 .Fa eckey .
240 .Pp
241 .Fn ECDSA_sign_setup
242 may be used to precompute parts of the signing operation.
243 .Fa eckey
244 is the private EC key and
245 .Fa ctx
246 is a pointer to a
247 .Vt BN_CTX
248 structure (or
249 .Dv NULL ) .
250 The precomputed values are returned in
251 .Fa kinv
252 and
253 .Fa rp
254 and can be used in a later call to
255 .Fa ECDSA_sign_ex
256 or
257 .Fa ECDSA_do_sign_ex .
258 .Pp
259 .Fn ECDSA_sign
260 is a wrapper function for
261 .Fa ECDSA_sign_ex
262 with
263 .Fa kinv
264 and
265 .Fa rp
266 set to
267 .Dv NULL .
268 .Pp
269 .Fn ECDSA_sign_ex
270 computes a digital signature of the
271 .Fa dgstlen
272 bytes hash value
273 .Fa dgst
274 using the private EC key
275 .Fa eckey
276 and the optional pre-computed values
277 .Fa kinv
278 and
279 .Fa rp .
280 The DER-encoded signature is stored in
281 .Fa sig
282 and its length is returned in
283 .Fa siglen .
284 Note:
285 .Fa sig
286 must point to
287 .Fn ECDSA_size
288 bytes of memory.
289 The parameter
290 .Fa type
291 is ignored.
292 .Pp
293 .Fn ECDSA_verify
294 verifies that the signature in
295 .Fa sig
296 of size
297 .Fa siglen
298 is a valid ECDSA signature of the hash value
299 .Fa dgst
300 of size
301 .Fa dgstlen
302 using the public key
303 .Fa eckey .
304 The parameter
305 .Fa type
306 is ignored.
307 .Pp
308 .Fn ECDSA_do_sign
309 is a wrapper function for
310 .Fn ECDSA_do_sign_ex
311 with
312 .Fa kinv
313 and
314 .Fa rp
315 set to
316 .Dv NULL .
317 .Pp
318 .Fn ECDSA_do_sign_ex
319 computes a digital signature of the
320 .Fa dgst_len
321 bytes hash value
322 .Fa dgst
323 using the private key
324 .Fa eckey
325 and the optional pre-computed values
326 .Fa kinv
327 and
328 .Fa rp .
329 The signature is returned in a newly allocated
330 .Vt ECDSA_SIG
331 structure (or
332 .Dv NULL
333 on error).
334 .Pp
335 .Fn ECDSA_do_verify
336 verifies that the signature
337 .Fa sig
338 is a valid ECDSA signature of the hash value
339 .Fa dgst
340 of size
341 .Fa dgst_len
342 using the public key
343 .Fa eckey .
344 .Sh RETURN VALUES
345 .Fn ECDSA_size
346 returns the maximum length signature or 0 on error.
347 .Pp
348 .Fn ECDSA_sign ,
349 .Fn ECDSA_sign_ex ,
350 and
351 .Fn ECDSA_sign_setup
352 return 1 if successful or 0 on error.
353 .Pp
354 .Fn ECDSA_do_sign
355 and
356 .Fn ECDSA_do_sign_ex
357 return a pointer to an allocated
358 .Vt ECDSA_SIG
359 structure or
360 .Dv NULL
361 on error.
362 .Pp
363 .Fn ECDSA_verify
364 and
365 .Fn ECDSA_do_verify
366 return 1 for a valid signature, 0 for an invalid signature and -1 on
367 error.
368 The error codes can be obtained by
369 .Xr ERR_get_error 3 .
370 .Sh EXAMPLES
371 Creating an ECDSA signature of given SHA-1 hash value using the named
372 curve secp192k1.
373 .Pp
374 First step: create an
375 .Vt EC_KEY
376 object.
377 This part is
378 .Em not
379 ECDSA specific.
380 .Bd -literal -offset indent
381 int ret;
382 ECDSA_SIG *sig;
383 EC_KEY *eckey;
385 eckey = EC_KEY_new_by_curve_name(NID_secp192k1);
386 if (eckey == NULL) {
387 /* error */
388 }
389 if (!EC_KEY_generate_key(eckey)) {
390 /* error */
391 }
392 .Ed
393 .Pp
394 Second step: compute the ECDSA signature of a SHA-1 hash value using
395 .Fn ECDSA_do_sign
396 .Bd -literal -offset indent
397 sig = ECDSA_do_sign(digest, 20, eckey);
398 if (sig == NULL) {
399 /* error */
400 }
401 .Ed
402 .Pp
403 or using
404 .Fn ECDSA_sign
405 .Bd -literal -offset indent
406 unsigned char *buffer, *pp;
407 int buf_len;
409 buf_len = ECDSA_size(eckey);
410 buffer = malloc(buf_len);
411 pp = buffer;
412 if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) {
413 /* error */
414 }
415 .Ed
416 .Pp
417 Third step: verify the created ECDSA signature using
418 .Fn ECDSA_do_verify
419 .Pp
420 .Dl ret = ECDSA_do_verify(digest, 20, sig, eckey);
421 .Pp
422 or using
423 .Fn ECDSA_verify
424 .Pp
425 .Dl ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey);
426 .Pp
427 and finally evaluate the return value:
428 .Bd -literal -offset indent
429 if (ret == -1) {
430 /* error */
431 } else if (ret == 0) {
432 /* incorrect signature */
433 } else {
434 /* ret == 1 */
435 /* signature ok */
436 }
437 .Ed
438 .Sh SEE ALSO
439 .Xr d2i_ECPKParameters 3 ,
440 .Xr DSA_new 3 ,
441 .Xr EC_GROUP_new 3 ,
442 .Xr EC_KEY_new 3 ,
443 .Xr ECDSA_set_ex_data 3 ,
444 .Xr EVP_DigestSignInit 3 ,
445 .Xr EVP_DigestVerifyInit 3 ,
446 .Xr RSA_new 3
447 .Sh STANDARDS
448 ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
449 (Digital Signature Standard, DSS)
450 .Sh HISTORY
451 The ECDSA implementation was first introduced in OpenSSL 0.9.8.
452 .Sh AUTHORS
453 .An Nils Larsch
454 for the OpenSSL project.