xref: /openbsd/lib/libcrypto/man/ECDSA_SIG_new.3 (revision 9b7c3dbb) 
1.Dd $Mdocdate: November 12 2015 $
2.Dt ECDSA_SIG_NEW 3
3.Os
4.Sh NAME
5.Nm ECDSA_SIG_new ,
6.Nm ECDSA_SIG_free ,
7.Nm i2d_ECDSA_SIG ,
8.Nm d2i_ECDSA_SIG ,
9.Nm ECDSA_size ,
10.Nm ECDSA_sign_setup ,
11.Nm ECDSA_sign ,
12.Nm ECDSA_sign_ex ,
13.Nm ECDSA_verify ,
14.Nm ECDSA_do_sign ,
15.Nm ECDSA_do_sign_ex ,
16.Nm ECDSA_do_verify ,
17.Nm ECDSA_OpenSSL ,
18.Nm ECDSA_get_default_method ,
19.Nm ECDSA_get_ex_data ,
20.Nm ECDSA_get_ex_new_index ,
21.Nm ECDSA_set_default_method ,
22.Nm ECDSA_set_ex_data ,
23.Nm ECDSA_set_method
24.Nd Elliptic Curve Digital Signature Algorithm
25.Sh SYNOPSIS
26.In openssl/ecdsa.h
27.Ft ECDSA_SIG*
28.Fo ECDSA_SIG_new
29.Fa void
30.Fc
31.Ft void
32.Fo ECDSA_SIG_free
33.Fa "ECDSA_SIG *sig"
34.Fc
35.Ft int
36.Fo i2d_ECDSA_SIG
37.Fa "const ECDSA_SIG *sig"
38.Fa "unsigned char **pp"
39.Fc
40.Ft ECDSA_SIG*
41.Fo d2i_ECDSA_SIG
42.Fa "ECDSA_SIG **sig"
43.Fa "const unsigned char **pp"
44.Fa "long len"
45.Fc
46.Ft ECDSA_SIG*
47.Fo ECDSA_do_sign
48.Fa "const unsigned char *dgst"
49.Fa "int dgst_len"
50.Fa "EC_KEY *eckey"
51.Fc
52.Ft ECDSA_SIG*
53.Fo ECDSA_do_sign_ex
54.Fa "const unsigned char *dgst"
55.Fa "int dgstlen"
56.Fa "const BIGNUM *kinv"
57.Fa "const BIGNUM *rp"
58.Fa "EC_KEY *eckey"
59.Fc
60.Ft int
61.Fo ECDSA_do_verify
62.Fa "const unsigned char *dgst"
63.Fa "int dgst_len"
64.Fa "const ECDSA_SIG *sig"
65.Fa "EC_KEY* eckey"
66.Fc
67.Ft int
68.Fo ECDSA_sign_setup
69.Fa "EC_KEY *eckey"
70.Fa "BN_CTX *ctx"
71.Fa "BIGNUM **kinv"
72.Fa "BIGNUM **rp"
73.Fc
74.Ft int
75.Fo ECDSA_sign
76.Fa "int type"
77.Fa "const unsigned char *dgst"
78.Fa "int dgstlen"
79.Fa "unsigned char *sig"
80.Fa "unsigned int *siglen"
81.Fa "EC_KEY *eckey"
82.Fc
83.Ft int
84.Fo ECDSA_sign_ex
85.Fa "int type"
86.Fa "const unsigned char *dgst"
87.Fa "int dgstlen"
88.Fa "unsigned char *sig"
89.Fa "unsigned int *siglen"
90.Fa "const BIGNUM *kinv"
91.Fa "const BIGNUM *rp"
92.Fa "EC_KEY *eckey"
93.Fc
94.Ft int
95.Fo ECDSA_verify
96.Fa "int type"
97.Fa "const unsigned char *dgst"
98.Fa "int dgstlen"
99.Fa "const unsigned char *sig"
100.Fa "int siglen"
101.Fa "EC_KEY *eckey"
102.Fc
103.Ft int
104.Fo ECDSA_size
105.Fa "const EC_KEY *eckey"
106.Fc
107.Ft const ECDSA_METHOD*
108.Fo ECDSA_OpenSSL
109.Fa void
110.Fc
111.Ft void
112.Fo ECDSA_set_default_method
113.Fa "const ECDSA_METHOD *meth"
114.Fc
115.Ft const ECDSA_METHOD*
116.Fo ECDSA_get_default_method
117.Fa void
118.Fc
119.Ft int
120.Fo ECDSA_set_method
121.Fa "EC_KEY *eckey"
122.Fa "const ECDSA_METHOD *meth"
123.Fc
124.Ft int
125.Fo ECDSA_get_ex_new_index
126.Fa "long argl"
127.Fa "void *argp"
128.Fa "CRYPTO_EX_new *new_func"
129.Fa "CRYPTO_EX_dup *dup_func"
130.Fa "CRYPTO_EX_free *free_func"
131.Fc
132.Ft int
133.Fo ECDSA_set_ex_data
134.Fa "EC_KEY *d"
135.Fa "int idx"
136.Fa "void *arg"
137.Fc
138.Ft void*
139.Fo ECDSA_get_ex_data
140.Fa "EC_KEY *d"
141.Fa "int idx"
142.Fc
143.Sh DESCRIPTION
144The
145.Vt ECDSA_SIG
146structure consists of two
147.Vt BIGNUM Ns s
148for the
149.Fa r
150and
151.Fa s
152value of an ECDSA signature (see X9.62 or FIPS 186-2).
153.Bd -literal -offset indent
154struct {
155	BIGNUM *r;
156	BIGNUM *s;
157} ECDSA_SIG;
158.Ed
159.Pp
160.Fn ECDSA_SIG_new
161allocates a new
162.Vt ECDSA_SIG
163structure (note: this function also allocates the
164.Vt BIGNUM Ns s )
165and initialize it.
166.Pp
167.Fn ECDSA_SIG_free
168frees the
169.Vt ECDSA_SIG
170structure
171.Fa sig .
172.Pp
173.Fn i2d_ECDSA_SIG
174creates the DER encoding of the ECDSA signature
175.Fa sig
176and writes the encoded signature to
177.Fa *pp
178(note: if
179.Fa pp
180is
181.Dv NULL ,
182.Fn i2d_ECDSA_SIG
183returns the expected length in bytes of the DER encoded signature).
184.Fn i2d_ECDSA_SIG
185returns the length of the DER encoded signature (or 0 on error).
186.Pp
187.Fn d2i_ECDSA_SIG
188decodes a DER encoded ECDSA signature and returns the decoded signature
189in a newly allocated
190.Vt ECDSA_SIG
191structure.
192.Fa *sig
193points to the buffer containing the DER encoded signature of size
194.Fa len .
195.Pp
196.Fn ECDSA_size
197returns the maximum length of a DER encoded ECDSA signature created with
198the private EC key
199.Fa eckey .
200.Pp
201.Fn ECDSA_sign_setup
202may be used to precompute parts of the signing operation.
203.Fa eckey
204is the private EC key and
205.Fa ctx
206is a pointer to a
207.Vt BN_CTX
208structure (or
209.Dv NULL ) .
210The precomputed values or returned in
211.Fa kinv
212and
213.Fa rp
214and can be used in a later call to
215.Fa ECDSA_sign_ex
216or
217.Fa ECDSA_do_sign_ex .
218.Pp
219.Fn ECDSA_sign
220is wrapper function for
221.Fa ECDSA_sign_ex
222with
223.Fa kinv
224and
225.Fa rp
226set to
227.Dv NULL .
228.Pp
229.Fn ECDSA_sign_ex
230computes a digital signature of the
231.Fa dgstlen
232bytes hash value
233.Fa dgst
234using the private EC key
235.Fa eckey
236and the optional pre-computed values
237.Fa kinv
238and
239.Fa rp .
240The DER encoded signatures is stored in
241.Fa sig
242and its length is returned in
243.Fa siglen .
244Note:
245.Fa sig
246must point to
247.Fn ECDSA_size
248bytes of memory.
249The parameter
250.Fa type
251is ignored.
252.Pp
253.Fn ECDSA_verify
254verifies that the signature in
255.Fa sig
256of size
257.Fa siglen
258is a valid ECDSA signature of the hash value
259.Fa dgst
260of size
261.Fa dgstlen
262using the public key
263.Fa eckey .
264The parameter
265.Fa type
266is ignored.
267.Pp
268.Fn ECDSA_do_sign
269is wrapper function for ECDSA_do_sign_ex with
270.Fa kinv
271and
272.Fa rp
273set to
274.Dv NULL .
275.Pp
276.Fn ECDSA_do_sign_ex
277computes a digital signature of the
278.Fa dgst_len
279bytes hash value
280.Fa dgst
281using the private key
282.Fa eckey
283and the optional pre-computed values
284.Fa kinv
285and
286.Fa rp .
287The signature is returned in a newly allocated
288.Vt ECDSA_SIG
289structure (or
290.Dv NULL
291on error).
292.Pp
293.Fn ECDSA_do_verify
294verifies that the signature
295.Fa sig
296is a valid ECDSA signature of the hash value
297.Fa dgst
298of size
299.Fa dgst_len
300using the public key
301.Fa eckey .
302.Sh RETURN VALUES
303.Fn ECDSA_size
304returns the maximum length signature or 0 on error.
305.Pp
306.Fn ECDSA_sign_setup
307and
308.Fn ECDSA_sign
309return 1 if successful or 0 on error.
310.Pp
311.Fn ECDSA_verify
312and
313.Fn ECDSA_do_verify
314return 1 for a valid signature, 0 for an invalid signature and -1 on
315error.
316The error codes can be obtained by
317.Xr ERR_get_error 3 .
318.Sh EXAMPLES
319Creating a ECDSA signature of given SHA-1 hash value using the named
320curve secp192k1.
321.Pp
322First step: Create an
323.Vt EC_KEY
324object.
325This part is
326.Em not
327ECDSA specific.
328.Bd -literal -offset indent
329int ret;
330ECDSA_SIG *sig;
331EC_KEY *eckey;
332
333eckey = EC_KEY_new_by_curve_name(NID_secp192k1);
334if (eckey == NULL) {
335	/* error */
336}
337if (!EC_KEY_generate_key(eckey)) {
338	/* error */
339}
340.Ed
341.Pp
342Second step: compute the ECDSA signature of a SHA-1 hash value using
343.Fn ECDSA_do_sign
344.Bd -literal -offset indent
345sig = ECDSA_do_sign(digest, 20, eckey);
346if (sig == NULL) {
347	/* error */
348}
349.Ed
350.Pp
351or using
352.Fn ECDSA_sign
353.Bd -literal -offset indent
354unsigned char *buffer, *pp;
355int buf_len;
356
357buf_len = ECDSA_size(eckey);
358buffer  = malloc(buf_len);
359pp = buffer;
360if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) {
361	/* error */
362}
363.Ed
364.Pp
365Third step: Verify the created ECDSA signature using
366.Fn ECDSA_do_verify
367.Pp
368.Dl ret = ECDSA_do_verify(digest, 20, sig, eckey);
369.Pp
370or using
371.Fn ECDSA_verify
372.Pp
373.Dl ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey);
374.Pp
375and finally evaluate the return value:
376.Bd -literal -offset indent
377if (ret == -1) {
378	/* error */
379} else if (ret == 0) {
380	/* incorrect signature */
381} else {
382	/* ret == 1 */
383	/* signature ok */
384}
385.Ed
386.Sh SEE ALSO
387.Xr dsa 3 ,
388.Xr rsa 3
389.Sh STANDARDS
390ANSI X9.62, US Federal Information Processing Standard FIPS 186-2
391(Digital Signature Standard, DSS)
392.Sh HISTORY
393The ecdsa implementation was first introduced in OpenSSL 0.9.8.
394.Sh AUTHORS
395.An Nils Larsch
396for the OpenSSL project.
397