| blob | 6e9ad3485a610d3b5be8a5c24f5d7b764b51533b |
1 .\" $NetBSD: libcrypto.pl,v 1.3 2007/11/27 22:16:03 christos Exp $
2 .\"
3 .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
4 .\"
5 .\" Standard preamble:
6 .\" ========================================================================
7 .de Sh \" Subsection heading
8 .br
9 .if t .Sp
10 .ne 5
11 .PP
12 \fB\\$1\fR
13 .PP
14 ..
15 .de Sp \" Vertical space (when we can't use .PP)
16 .if t .sp .5v
17 .if n .sp
18 ..
19 .de Vb \" Begin verbatim text
20 .ft CW
21 .nf
22 .ne \\$1
23 ..
24 .de Ve \" End verbatim text
25 .ft R
26 .fi
27 ..
28 .\" Set up some character translations and predefined strings. \*(-- will
29 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
30 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
31 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
32 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
33 .\" nothing in troff, for use with C<>.
34 .tr \(*W-
35 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
36 .ie n \{\
37 . ds -- \(*W-
38 . ds PI pi
39 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
40 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
41 . ds L" ""
42 . ds R" ""
43 . ds C` ""
44 . ds C' ""
45 'br\}
46 .el\{\
47 . ds -- \|\(em\|
48 . ds PI \(*p
49 . ds L" ``
50 . ds R" ''
51 'br\}
52 .\"
53 .\" Escape single quotes in literal strings from groff's Unicode transform.
54 .ie \n(.g .ds Aq \(aq
55 .el .ds Aq '
56 .\"
57 .\" If the F register is turned on, we'll generate index entries on stderr for
58 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
59 .\" entries marked with X<> in POD. Of course, you'll have to process the
60 .\" output yourself in some meaningful fashion.
61 .ie \nF \{\
62 . de IX
63 . tm Index:\\$1\t\\n%\t"\\$2"
64 ..
65 . nr % 0
66 . rr F
67 .\}
68 .el \{\
69 . de IX
70 ..
71 .\}
72 .\"
73 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
74 .\" Fear. Run. Save yourself. No user-serviceable parts.
75 . \" fudge factors for nroff and troff
76 .if n \{\
77 . ds #H 0
78 . ds #V .8m
79 . ds #F .3m
80 . ds #[ \f1
81 . ds #] \fP
82 .\}
83 .if t \{\
84 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . ds #V .6m
86 . ds #F 0
87 . ds #[ \&
88 . ds #] \&
89 .\}
90 . \" simple accents for nroff and troff
91 .if n \{\
92 . ds ' \&
93 . ds ` \&
94 . ds ^ \&
95 . ds , \&
96 . ds ~ ~
97 . ds /
98 .\}
99 .if t \{\
100 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
101 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
102 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
103 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
104 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
105 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
106 .\}
107 . \" troff and (daisy-wheel) nroff accents
108 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
109 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
110 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
111 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
112 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
113 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
114 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
115 .ds ae a\h'-(\w'a'u*4/10)'e
116 .ds Ae A\h'-(\w'A'u*4/10)'E
117 . \" corrections for vroff
118 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
119 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
120 . \" for low resolution devices (crt and lpr)
121 .if \n(.H>23 .if \n(.V>19 \
122 \{\
123 . ds : e
124 . ds 8 ss
125 . ds o a
126 . ds d- d\h'-1'\(ga
127 . ds D- D\h'-1'\(hy
128 . ds th \o'bp'
129 . ds Th \o'LP'
130 . ds ae ae
131 . ds Ae AE
132 .\}
133 .rm #[ #] #H #V #F C
134 .\" ========================================================================
135 .\"
136 .IX Title "ecdsa 3"
137 .TH ecdsa 3 "2005-05-19" "1.1.0-dev" "OpenSSL"
138 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
139 .\" way too many mistakes in technical documents.
140 .if n .ad l
141 .nh
142 .SH "NAME"
143 ecdsa \- Elliptic Curve Digital Signature Algorithm
144 .SH "LIBRARY"
145 libcrypto, -lcrypto
146 .SH "SYNOPSIS"
147 .IX Header "SYNOPSIS"
148 .Vb 1
149 \& #include <openssl/ecdsa.h>
150 \&
151 \& ECDSA_SIG* ECDSA_SIG_new(void);
152 \& void ECDSA_SIG_free(ECDSA_SIG *sig);
153 \& int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp);
154 \& ECDSA_SIG* d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp,
155 \& long len);
156 \&
157 \& ECDSA_SIG* ECDSA_do_sign(const unsigned char *dgst, int dgst_len,
158 \& EC_KEY *eckey);
159 \& ECDSA_SIG* ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen,
160 \& const BIGNUM *kinv, const BIGNUM *rp,
161 \& EC_KEY *eckey);
162 \& int ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
163 \& const ECDSA_SIG *sig, EC_KEY* eckey);
164 \& int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx,
165 \& BIGNUM **kinv, BIGNUM **rp);
166 \& int ECDSA_sign(int type, const unsigned char *dgst,
167 \& int dgstlen, unsigned char *sig,
168 \& unsigned int *siglen, EC_KEY *eckey);
169 \& int ECDSA_sign_ex(int type, const unsigned char *dgst,
170 \& int dgstlen, unsigned char *sig,
171 \& unsigned int *siglen, const BIGNUM *kinv,
172 \& const BIGNUM *rp, EC_KEY *eckey);
173 \& int ECDSA_verify(int type, const unsigned char *dgst,
174 \& int dgstlen, const unsigned char *sig,
175 \& int siglen, EC_KEY *eckey);
176 \& int ECDSA_size(const EC_KEY *eckey);
177 \&
178 \& const ECDSA_METHOD* ECDSA_OpenSSL(void);
179 \& void ECDSA_set_default_method(const ECDSA_METHOD *meth);
180 \& const ECDSA_METHOD* ECDSA_get_default_method(void);
181 \& int ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth);
182 \&
183 \& int ECDSA_get_ex_new_index(long argl, void *argp,
184 \& CRYPTO_EX_new *new_func,
185 \& CRYPTO_EX_dup *dup_func,
186 \& CRYPTO_EX_free *free_func);
187 \& int ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg);
188 \& void* ECDSA_get_ex_data(EC_KEY *d, int idx);
189 .Ve
190 .SH "DESCRIPTION"
191 .IX Header "DESCRIPTION"
192 The \fB\s-1ECDSA_SIG\s0\fR structure consists of two BIGNUMs for the
193 r and s value of a \s-1ECDSA\s0 signature (see X9.62 or \s-1FIPS\s0 186\-2).
194 .PP
195 .Vb 5
196 \& struct
197 \& {
198 \& BIGNUM *r;
199 \& BIGNUM *s;
200 \& } ECDSA_SIG;
201 .Ve
202 .PP
203 \&\fIECDSA_SIG_new()\fR allocates a new \fB\s-1ECDSA_SIG\s0\fR structure (note: this
204 function also allocates the BIGNUMs) and initialize it.
205 .PP
206 \&\fIECDSA_SIG_free()\fR frees the \fB\s-1ECDSA_SIG\s0\fR structure \fBsig\fR.
207 .PP
208 \&\fIi2d_ECDSA_SIG()\fR creates the \s-1DER\s0 encoding of the \s-1ECDSA\s0 signature
209 \&\fBsig\fR and writes the encoded signature to \fB*pp\fR (note: if \fBpp\fR
210 is \s-1NULL\s0 \fBi2d_ECDSA_SIG\fR returns the expected length in bytes of
211 the \s-1DER\s0 encoded signature). \fBi2d_ECDSA_SIG\fR returns the length
212 of the \s-1DER\s0 encoded signature (or 0 on error).
213 .PP
214 \&\fId2i_ECDSA_SIG()\fR decodes a \s-1DER\s0 encoded \s-1ECDSA\s0 signature and returns
215 the decoded signature in a newly allocated \fB\s-1ECDSA_SIG\s0\fR structure.
216 \&\fB*sig\fR points to the buffer containing the \s-1DER\s0 encoded signature
217 of size \fBlen\fR.
218 .PP
219 \&\fIECDSA_size()\fR returns the maximum length of a \s-1DER\s0 encoded
220 \&\s-1ECDSA\s0 signature created with the private \s-1EC\s0 key \fBeckey\fR.
221 .PP
222 \&\fIECDSA_sign_setup()\fR may be used to precompute parts of the
223 signing operation. \fBeckey\fR is the private \s-1EC\s0 key and \fBctx\fR
224 is a pointer to \fB\s-1BN_CTX\s0\fR structure (or \s-1NULL\s0). The precomputed
225 values or returned in \fBkinv\fR and \fBrp\fR and can be used in a
226 later call to \fBECDSA_sign_ex\fR or \fBECDSA_do_sign_ex\fR.
227 .PP
228 \&\fIECDSA_sign()\fR is wrapper function for ECDSA_sign_ex with \fBkinv\fR
229 and \fBrp\fR set to \s-1NULL\s0.
230 .PP
231 \&\fIECDSA_sign_ex()\fR computes a digital signature of the \fBdgstlen\fR bytes
232 hash value \fBdgst\fR using the private \s-1EC\s0 key \fBeckey\fR and the optional
233 pre-computed values \fBkinv\fR and \fBrp\fR. The \s-1DER\s0 encoded signatures is
234 stored in \fBsig\fR and it's length is returned in \fBsig_len\fR. Note: \fBsig\fR
235 must point to \fBECDSA_size\fR bytes of memory. The parameter \fBtype\fR
236 is ignored.
237 .PP
238 \&\fIECDSA_verify()\fR verifies that the signature in \fBsig\fR of size
239 \&\fBsiglen\fR is a valid \s-1ECDSA\s0 signature of the hash value
240 value \fBdgst\fR of size \fBdgstlen\fR using the public key \fBeckey\fR.
241 The parameter \fBtype\fR is ignored.
242 .PP
243 \&\fIECDSA_do_sign()\fR is wrapper function for ECDSA_do_sign_ex with \fBkinv\fR
244 and \fBrp\fR set to \s-1NULL\s0.
245 .PP
246 \&\fIECDSA_do_sign_ex()\fR computes a digital signature of the \fBdgst_len\fR
247 bytes hash value \fBdgst\fR using the private key \fBeckey\fR and the
248 optional pre-computed values \fBkinv\fR and \fBrp\fR. The signature is
249 returned in a newly allocated \fB\s-1ECDSA_SIG\s0\fR structure (or \s-1NULL\s0 on error).
250 .PP
251 \&\fIECDSA_do_verify()\fR verifies that the signature \fBsig\fR is a valid
252 \&\s-1ECDSA\s0 signature of the hash value \fBdgst\fR of size \fBdgst_len\fR
253 using the public key \fBeckey\fR.
254 .SH "RETURN VALUES"
255 .IX Header "RETURN VALUES"
256 \&\fIECDSA_size()\fR returns the maximum length signature or 0 on error.
257 .PP
258 \&\fIECDSA_sign_setup()\fR and \fIECDSA_sign()\fR return 1 if successful or \-1
259 on error.
260 .PP
261 \&\fIECDSA_verify()\fR and \fIECDSA_do_verify()\fR return 1 for a valid
262 signature, 0 for an invalid signature and \-1 on error.
263 The error codes can be obtained by \fIERR_get_error\fR\|(3).
264 .SH "EXAMPLES"
265 .IX Header "EXAMPLES"
266 Creating a \s-1ECDSA\s0 signature of given \s-1SHA\-1\s0 hash value using the
267 named curve secp192k1.
268 .PP
269 First step: create a \s-1EC_KEY\s0 object (note: this part is \fBnot\fR \s-1ECDSA\s0
270 specific)
271 .PP
272 .Vb 10
273 \& int ret;
274 \& ECDSA_SIG *sig;
275 \& EC_KEY *eckey = EC_KEY_new();
276 \& if (eckey == NULL)
277 \& {
278 \& /* error */
279 \& }
280 \& key\->group = EC_GROUP_new_by_nid(NID_secp192k1);
281 \& if (key\->group == NULL)
282 \& {
283 \& /* error */
284 \& }
285 \& if (!EC_KEY_generate_key(eckey))
286 \& {
287 \& /* error */
288 \& }
289 .Ve
290 .PP
291 Second step: compute the \s-1ECDSA\s0 signature of a \s-1SHA\-1\s0 hash value
292 using \fBECDSA_do_sign\fR
293 .PP
294 .Vb 5
295 \& sig = ECDSA_do_sign(digest, 20, eckey);
296 \& if (sig == NULL)
297 \& {
298 \& /* error */
299 \& }
300 .Ve
301 .PP
302 or using \fBECDSA_sign\fR
303 .PP
304 .Vb 9
305 \& unsigned char *buffer, *pp;
306 \& int buf_len;
307 \& buf_len = ECDSA_size(eckey);
308 \& buffer = OPENSSL_malloc(buf_len);
309 \& pp = buffer;
310 \& if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey);
311 \& {
312 \& /* error */
313 \& }
314 .Ve
315 .PP
316 Third step: verify the created \s-1ECDSA\s0 signature using \fBECDSA_do_verify\fR
317 .PP
318 .Vb 1
319 \& ret = ECDSA_do_verify(digest, 20, sig, eckey);
320 .Ve
321 .PP
322 or using \fBECDSA_verify\fR
323 .PP
324 .Vb 1
325 \& ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey);
326 .Ve
327 .PP
328 and finally evaluate the return value:
329 .PP
330 .Vb 12
331 \& if (ret == \-1)
332 \& {
333 \& /* error */
334 \& }
335 \& else if (ret == 0)
336 \& {
337 \& /* incorrect signature */
338 \& }
339 \& else /* ret == 1 */
340 \& {
341 \& /* signature ok */
342 \& }
343 .Ve
344 .SH "CONFORMING TO"
345 .IX Header "CONFORMING TO"
346 \&\s-1ANSI\s0 X9.62, \s-1US\s0 Federal Information Processing Standard \s-1FIPS\s0 186\-2
347 (Digital Signature Standard, \s-1DSS\s0)
348 .SH "SEE ALSO"
349 .IX Header "SEE ALSO"
350 \&\fIopenssl_dsa\fR\|(3), \fIopenssl_rsa\fR\|(3)
351 .SH "HISTORY"
352 .IX Header "HISTORY"
353 The ecdsa implementation was first introduced in OpenSSL 0.9.8
354 .SH "AUTHOR"
355 .IX Header "AUTHOR"
356 Nils Larsch for the OpenSSL project (http://www.openssl.org).