76c5a4aa2ae01bca9206cb59c9f518f6491006a4
[openssl.git] / crypto / ecdsa / ecdsa.h
1 /* crypto/ecdsa/ecdsa.h */
2 /**
3  * \file   crypto/ecdsa/ecdsa.h Include file for the OpenSSL ECDSA functions
4  * \author Written by Nils Larsch for the OpenSSL project
5  */
6 /* ====================================================================
7  * Copyright (c) 2000-2003 The OpenSSL Project.  All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * 1. Redistributions of source code must retain the above copyright
14  *    notice, this list of conditions and the following disclaimer. 
15  *
16  * 2. Redistributions in binary form must reproduce the above copyright
17  *    notice, this list of conditions and the following disclaimer in
18  *    the documentation and/or other materials provided with the
19  *    distribution.
20  *
21  * 3. All advertising materials mentioning features or use of this
22  *    software must display the following acknowledgment:
23  *    "This product includes software developed by the OpenSSL Project
24  *    for use in the OpenSSL Toolkit. (http://www.OpenSSL.org/)"
25  *
26  * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
27  *    endorse or promote products derived from this software without
28  *    prior written permission. For written permission, please contact
29  *    licensing@OpenSSL.org.
30  *
31  * 5. Products derived from this software may not be called "OpenSSL"
32  *    nor may "OpenSSL" appear in their names without prior written
33  *    permission of the OpenSSL Project.
34  *
35  * 6. Redistributions of any form whatsoever must retain the following
36  *    acknowledgment:
37  *    "This product includes software developed by the OpenSSL Project
38  *    for use in the OpenSSL Toolkit (http://www.OpenSSL.org/)"
39  *
40  * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
41  * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
43  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
44  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
46  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
47  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
49  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
50  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
51  * OF THE POSSIBILITY OF SUCH DAMAGE.
52  * ====================================================================
53  *
54  * This product includes cryptographic software written by Eric Young
55  * (eay@cryptsoft.com).  This product includes software written by Tim
56  * Hudson (tjh@cryptsoft.com).
57  *
58  */
59 #ifndef HEADER_ECDSA_H
60 #define HEADER_ECDSA_H
61
62 #include <openssl/opensslconf.h>
63
64 #ifdef OPENSSL_NO_ECDSA
65 #error ECDSA is disabled.
66 #endif
67
68 #include <openssl/ec.h>
69 #include <openssl/ossl_typ.h>
70 #ifndef OPENSSL_NO_DEPRECATED
71 #include <openssl/bn.h>
72 #endif
73
74 #ifdef __cplusplus
75 extern "C" {
76 #endif
77
78 typedef struct ECDSA_SIG_st
79         {
80         BIGNUM *r;
81         BIGNUM *s;
82         } ECDSA_SIG;
83
84 /** ECDSA_SIG *ECDSA_SIG_new(void)
85  * allocates and initialize a ECDSA_SIG structure
86  * \return pointer to a ECDSA_SIG structure or NULL if an error occurred
87  */
88 ECDSA_SIG *ECDSA_SIG_new(void);
89
90 /** ECDSA_SIG_free
91  * frees a ECDSA_SIG structure
92  * \param a pointer to the ECDSA_SIG structure
93  */
94 void      ECDSA_SIG_free(ECDSA_SIG *a);
95
96 /** i2d_ECDSA_SIG
97  * DER encode content of ECDSA_SIG object (note: this function modifies *pp
98  * (*pp += length of the DER encoded signature)).
99  * \param a  pointer to the ECDSA_SIG object
100  * \param pp pointer to a unsigned char pointer for the output or NULL
101  * \return the length of the DER encoded ECDSA_SIG object or 0 
102  */
103 int       i2d_ECDSA_SIG(const ECDSA_SIG *a, unsigned char **pp);
104
105 /** d2i_ECDSA_SIG
106  * decodes a DER encoded ECDSA signature (note: this function changes *pp
107  * (*pp += len)). 
108  * \param v pointer to ECDSA_SIG pointer (may be NULL)
109  * \param pp buffer with the DER encoded signature
110  * \param len bufferlength
111  * \return pointer to the decoded ECDSA_SIG structure (or NULL)
112  */
113 ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **v, const unsigned char **pp, long len);
114
115 /** ECDSA_do_sign
116  * computes the ECDSA signature of the given hash value using
117  * the supplied private key and returns the created signature.
118  * \param dgst pointer to the hash value
119  * \param dgst_len length of the hash value
120  * \param eckey pointer to the EC_KEY object containing a private EC key
121  * \return pointer to a ECDSA_SIG structure or NULL
122  */
123 ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst,int dgst_len,EC_KEY *eckey);
124
125 /** ECDSA_do_sign_ex
126  * computes ECDSA signature of a given hash value using the supplied
127  * private key (note: sig must point to ECDSA_size(eckey) bytes of memory).
128  * \param dgst pointer to the hash value to sign
129  * \param dgstlen length of the hash value
130  * \param kinv optional pointer to a pre-computed inverse k
131  * \param rp optional pointer to the pre-computed rp value (see 
132  *        ECDSA_sign_setup
133  * \param eckey pointer to the EC_KEY object containing a private EC key
134  * \return pointer to a ECDSA_SIG structure or NULL
135  */
136 ECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen, 
137                 const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey);
138
139 /** ECDSA_do_verify
140  * verifies that the supplied signature is a valid ECDSA
141  * signature of the supplied hash value using the supplied public key.
142  * \param dgst pointer to the hash value
143  * \param dgst_len length of the hash value
144  * \param sig  pointer to the ECDSA_SIG structure
145  * \param eckey pointer to the EC_KEY object containing a public EC key
146  * \return 1 if the signature is valid, 0 if the signature is invalid and -1 on error
147  */
148 int       ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
149                 const ECDSA_SIG *sig, EC_KEY* eckey);
150
151 const ECDSA_METHOD *ECDSA_OpenSSL(void);
152
153 /** ECDSA_set_default_method
154  * sets the default ECDSA method
155  * \param meth the new default ECDSA_METHOD
156  */
157 void      ECDSA_set_default_method(const ECDSA_METHOD *meth);
158
159 /** ECDSA_get_default_method
160  * returns the default ECDSA method
161  * \return pointer to ECDSA_METHOD structure containing the default method
162  */
163 const ECDSA_METHOD *ECDSA_get_default_method(void);
164
165 /** ECDSA_set_method
166  * sets method to be used for the ECDSA operations
167  * \param eckey pointer to the EC_KEY object
168  * \param meth  pointer to the new method
169  * \return 1 on success and 0 otherwise 
170  */
171 int       ECDSA_set_method(EC_KEY *eckey, const ECDSA_METHOD *meth);
172
173 /** ECDSA_size
174  * returns the maximum length of the DER encoded signature
175  * \param  eckey pointer to a EC_KEY object
176  * \return numbers of bytes required for the DER encoded signature
177  */
178 int       ECDSA_size(const EC_KEY *eckey);
179
180 /** ECDSA_sign_setup
181  * precompute parts of the signing operation. 
182  * \param eckey pointer to the EC_KEY object containing a private EC key
183  * \param ctx  pointer to a BN_CTX object (may be NULL)
184  * \param kinv pointer to a BIGNUM pointer for the inverse of k
185  * \param rp   pointer to a BIGNUM pointer for x coordinate of k * generator
186  * \return 1 on success and 0 otherwise
187  */
188 int       ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, 
189                 BIGNUM **rp);
190
191 /** ECDSA_sign
192  * computes ECDSA signature of a given hash value using the supplied
193  * private key (note: sig must point to ECDSA_size(eckey) bytes of memory).
194  * \param type this parameter is ignored
195  * \param dgst pointer to the hash value to sign
196  * \param dgstlen length of the hash value
197  * \param sig buffer to hold the DER encoded signature
198  * \param siglen pointer to the length of the returned signature
199  * \param eckey pointer to the EC_KEY object containing a private EC key
200  * \return 1 on success and 0 otherwise
201  */
202 int       ECDSA_sign(int type, const unsigned char *dgst, int dgstlen, 
203                 unsigned char *sig, unsigned int *siglen, EC_KEY *eckey);
204
205
206 /** ECDSA_sign_ex
207  * computes ECDSA signature of a given hash value using the supplied
208  * private key (note: sig must point to ECDSA_size(eckey) bytes of memory).
209  * \param type this parameter is ignored
210  * \param dgst pointer to the hash value to sign
211  * \param dgstlen length of the hash value
212  * \param sig buffer to hold the DER encoded signature
213  * \param siglen pointer to the length of the returned signature
214  * \param kinv optional pointer to a pre-computed inverse k
215  * \param rp optional pointer to the pre-computed rp value (see 
216  *        ECDSA_sign_setup
217  * \param eckey pointer to the EC_KEY object containing a private EC key
218  * \return 1 on success and 0 otherwise
219  */
220 int       ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen, 
221                 unsigned char *sig, unsigned int *siglen, const BIGNUM *kinv,
222                 const BIGNUM *rp, EC_KEY *eckey);
223
224 /** ECDSA_verify
225  * verifies that the given signature is valid ECDSA signature
226  * of the supplied hash value using the specified public key.
227  * \param type this parameter is ignored
228  * \param dgst pointer to the hash value 
229  * \param dgstlen length of the hash value
230  * \param sig  pointer to the DER encoded signature
231  * \param siglen length of the DER encoded signature
232  * \param eckey pointer to the EC_KEY object containing a public EC key
233  * \return 1 if the signature is valid, 0 if the signature is invalid and -1 on error
234  */
235 int       ECDSA_verify(int type, const unsigned char *dgst, int dgstlen, 
236                 const unsigned char *sig, int siglen, EC_KEY *eckey);
237
238 /* the standard ex_data functions */
239 int       ECDSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new 
240                 *new_func, CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
241 int       ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg);
242 void      *ECDSA_get_ex_data(EC_KEY *d, int idx);
243
244
245 /* BEGIN ERROR CODES */
246 /* The following lines are auto generated by the script mkerr.pl. Any changes
247  * made after this point may be overwritten when the script is next run.
248  */
249 void ERR_load_ECDSA_strings(void);
250
251 /* Error codes for the ECDSA functions. */
252
253 /* Function codes. */
254 #define ECDSA_F_ECDSA_DATA_NEW_METHOD                    100
255 #define ECDSA_F_ECDSA_DO_SIGN                            101
256 #define ECDSA_F_ECDSA_DO_VERIFY                          102
257 #define ECDSA_F_ECDSA_SIGN_SETUP                         103
258
259 /* Reason codes. */
260 #define ECDSA_R_BAD_SIGNATURE                            100
261 #define ECDSA_R_DATA_TOO_LARGE_FOR_KEY_SIZE              101
262 #define ECDSA_R_ERR_EC_LIB                               102
263 #define ECDSA_R_MISSING_PARAMETERS                       103
264 #define ECDSA_R_RANDOM_NUMBER_GENERATION_FAILED          104
265 #define ECDSA_R_SIGNATURE_MALLOC_FAILED                  105
266
267 #ifdef  __cplusplus
268 }
269 #endif
270 #endif