]>
Commit | Line | Data |
---|---|---|
5075521e GT |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
aafbe1cc | 5 | ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size, ECDSA_sign_setup, ECDSA_sign, ECDSA_sign_ex, ECDSA_verify, ECDSA_do_sign, ECDSA_do_sign_ex, ECDSA_do_verify - Elliptic Curve Digital Signature Algorithm |
5075521e GT |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ecdsa.h> | |
10 | ||
11 | ECDSA_SIG* ECDSA_SIG_new(void); | |
12 | void ECDSA_SIG_free(ECDSA_SIG *sig); | |
13 | int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp); | |
14 | ECDSA_SIG* d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, | |
15 | long len); | |
16 | ||
5075521e GT |
17 | ECDSA_SIG* ECDSA_do_sign(const unsigned char *dgst, int dgst_len, |
18 | EC_KEY *eckey); | |
b67d9889 NL |
19 | ECDSA_SIG* ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen, |
20 | const BIGNUM *kinv, const BIGNUM *rp, | |
21 | EC_KEY *eckey); | |
5075521e | 22 | int ECDSA_do_verify(const unsigned char *dgst, int dgst_len, |
0b3fc6e6 | 23 | const ECDSA_SIG *sig, EC_KEY* eckey); |
5075521e GT |
24 | int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, |
25 | BIGNUM **kinv, BIGNUM **rp); | |
26 | int ECDSA_sign(int type, const unsigned char *dgst, | |
27 | int dgstlen, unsigned char *sig, | |
28 | unsigned int *siglen, EC_KEY *eckey); | |
b67d9889 NL |
29 | int ECDSA_sign_ex(int type, const unsigned char *dgst, |
30 | int dgstlen, unsigned char *sig, | |
31 | unsigned int *siglen, const BIGNUM *kinv, | |
32 | const BIGNUM *rp, EC_KEY *eckey); | |
5075521e GT |
33 | int ECDSA_verify(int type, const unsigned char *dgst, |
34 | int dgstlen, const unsigned char *sig, | |
35 | int siglen, EC_KEY *eckey); | |
36 | int ECDSA_size(const EC_KEY *eckey); | |
37 | ||
38 | const ECDSA_METHOD* ECDSA_OpenSSL(void); | |
39 | void ECDSA_set_default_method(const ECDSA_METHOD *meth); | |
40 | const ECDSA_METHOD* ECDSA_get_default_method(void); | |
41 | int ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth); | |
42 | ||
5075521e GT |
43 | =head1 DESCRIPTION |
44 | ||
45 | The B<ECDSA_SIG> structure consists of two BIGNUMs for the | |
46 | r and s value of a ECDSA signature (see X9.62 or FIPS 186-2). | |
47 | ||
48 | struct | |
49 | { | |
50 | BIGNUM *r; | |
51 | BIGNUM *s; | |
52 | } ECDSA_SIG; | |
53 | ||
54 | ECDSA_SIG_new() allocates a new B<ECDSA_SIG> structure (note: this | |
55 | function also allocates the BIGNUMs) and initialize it. | |
56 | ||
57 | ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>. | |
58 | ||
59 | i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature | |
60 | B<sig> and writes the encoded signature to B<*pp> (note: if B<pp> | |
61 | is NULL B<i2d_ECDSA_SIG> returns the expected length in bytes of | |
62 | the DER encoded signature). B<i2d_ECDSA_SIG> returns the length | |
63 | of the DER encoded signature (or 0 on error). | |
64 | ||
65 | d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns | |
66 | the decoded signature in a newly allocated B<ECDSA_SIG> structure. | |
67 | B<*sig> points to the buffer containing the DER encoded signature | |
68 | of size B<len>. | |
69 | ||
5075521e GT |
70 | ECDSA_size() returns the maximum length of a DER encoded |
71 | ECDSA signature created with the private EC key B<eckey>. | |
72 | ||
73 | ECDSA_sign_setup() may be used to precompute parts of the | |
74 | signing operation. B<eckey> is the private EC key and B<ctx> | |
75 | is a pointer to B<BN_CTX> structure (or NULL). The precomputed | |
76 | values or returned in B<kinv> and B<rp> and can be used in a | |
b67d9889 | 77 | later call to B<ECDSA_sign_ex> or B<ECDSA_do_sign_ex>. |
5075521e | 78 | |
b67d9889 NL |
79 | ECDSA_sign() is wrapper function for ECDSA_sign_ex with B<kinv> |
80 | and B<rp> set to NULL. | |
81 | ||
82 | ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes | |
83 | hash value B<dgst> using the private EC key B<eckey> and the optional | |
84 | pre-computed values B<kinv> and B<rp>. The DER encoded signatures is | |
85 | stored in B<sig> and it's length is returned in B<sig_len>. Note: B<sig> | |
5075521e GT |
86 | must point to B<ECDSA_size> bytes of memory. The parameter B<type> |
87 | is ignored. | |
88 | ||
89 | ECDSA_verify() verifies that the signature in B<sig> of size | |
90 | B<siglen> is a valid ECDSA signature of the hash value | |
36019f70 | 91 | B<dgst> of size B<dgstlen> using the public key B<eckey>. |
5075521e GT |
92 | The parameter B<type> is ignored. |
93 | ||
b67d9889 NL |
94 | ECDSA_do_sign() is wrapper function for ECDSA_do_sign_ex with B<kinv> |
95 | and B<rp> set to NULL. | |
96 | ||
97 | ECDSA_do_sign_ex() computes a digital signature of the B<dgst_len> | |
98 | bytes hash value B<dgst> using the private key B<eckey> and the | |
99 | optional pre-computed values B<kinv> and B<rp>. The signature is | |
100 | returned in a newly allocated B<ECDSA_SIG> structure (or NULL on error). | |
5075521e GT |
101 | |
102 | ECDSA_do_verify() verifies that the signature B<sig> is a valid | |
103 | ECDSA signature of the hash value B<dgst> of size B<dgst_len> | |
104 | using the public key B<eckey>. | |
105 | ||
106 | =head1 RETURN VALUES | |
107 | ||
108 | ECDSA_size() returns the maximum length signature or 0 on error. | |
109 | ||
62d7dd5f | 110 | ECDSA_sign_setup() and ECDSA_sign() return 1 if successful or 0 |
5075521e GT |
111 | on error. |
112 | ||
113 | ECDSA_verify() and ECDSA_do_verify() return 1 for a valid | |
114 | signature, 0 for an invalid signature and -1 on error. | |
9b86974e | 115 | The error codes can be obtained by L<ERR_get_error(3)>. |
5075521e GT |
116 | |
117 | =head1 EXAMPLES | |
118 | ||
119 | Creating a ECDSA signature of given SHA-1 hash value using the | |
120 | named curve secp192k1. | |
121 | ||
122 | First step: create a EC_KEY object (note: this part is B<not> ECDSA | |
123 | specific) | |
124 | ||
125 | int ret; | |
126 | ECDSA_SIG *sig; | |
36019f70 DSH |
127 | EC_KEY *eckey; |
128 | eckey = EC_KEY_new_by_curve_name(NID_secp192k1); | |
5075521e GT |
129 | if (eckey == NULL) |
130 | { | |
131 | /* error */ | |
132 | } | |
5075521e GT |
133 | if (!EC_KEY_generate_key(eckey)) |
134 | { | |
135 | /* error */ | |
136 | } | |
137 | ||
138 | Second step: compute the ECDSA signature of a SHA-1 hash value | |
139 | using B<ECDSA_do_sign> | |
140 | ||
141 | sig = ECDSA_do_sign(digest, 20, eckey); | |
142 | if (sig == NULL) | |
143 | { | |
144 | /* error */ | |
145 | } | |
146 | ||
147 | or using B<ECDSA_sign> | |
148 | ||
149 | unsigned char *buffer, *pp; | |
150 | int buf_len; | |
151 | buf_len = ECDSA_size(eckey); | |
152 | buffer = OPENSSL_malloc(buf_len); | |
153 | pp = buffer; | |
154 | if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey); | |
155 | { | |
156 | /* error */ | |
157 | } | |
158 | ||
159 | Third step: verify the created ECDSA signature using B<ECDSA_do_verify> | |
160 | ||
161 | ret = ECDSA_do_verify(digest, 20, sig, eckey); | |
162 | ||
163 | or using B<ECDSA_verify> | |
164 | ||
165 | ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey); | |
166 | ||
167 | and finally evaluate the return value: | |
168 | ||
169 | if (ret == -1) | |
170 | { | |
171 | /* error */ | |
172 | } | |
173 | else if (ret == 0) | |
174 | { | |
175 | /* incorrect signature */ | |
176 | } | |
177 | else /* ret == 1 */ | |
178 | { | |
179 | /* signature ok */ | |
180 | } | |
181 | ||
182 | =head1 CONFORMING TO | |
183 | ||
184 | ANSI X9.62, US Federal Information Processing Standard FIPS 186-2 | |
185 | (Digital Signature Standard, DSS) | |
186 | ||
187 | =head1 SEE ALSO | |
188 | ||
9b86974e | 189 | L<dsa(3)>, L<rsa(3)> |
5075521e | 190 | |
5075521e | 191 | =cut |