more const
[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 /* Already defined in ossl_typ.h */
79 /* typedef struct ecdsa_method ECDSA_METHOD; */
80
81 typedef struct ECDSA_SIG_st
82         {
83         BIGNUM *r;
84         BIGNUM *s;
85         } ECDSA_SIG;
86
87 struct ecdsa_method 
88         {
89         const char *name;
90         ECDSA_SIG *(*ecdsa_do_sign)(const unsigned char *dgst, int dgst_len, 
91                         EC_KEY *eckey);
92         int (*ecdsa_sign_setup)(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, 
93                         BIGNUM **r);
94         int (*ecdsa_do_verify)(const unsigned char *dgst, int dgst_len, 
95                         const ECDSA_SIG *sig, EC_KEY *eckey);
96 #if 0
97         int (*init)(EC_KEY *eckey);
98         int (*finish)(EC_KEY *eckey);
99 #endif
100         int flags;
101         char *app_data;
102         };
103
104 typedef struct ecdsa_data_st {
105         /* EC_KEY_METH_DATA part */
106         int (*init)(EC_KEY *);
107         void (*finish)(EC_KEY *);
108         /* method (ECDSA) specific part */
109         BIGNUM  *kinv;  /* signing pre-calc */
110         BIGNUM  *r;     /* signing pre-calc */
111         ENGINE  *engine;
112         int     flags;
113         const ECDSA_METHOD *meth;
114         CRYPTO_EX_DATA ex_data;
115 } ECDSA_DATA; 
116
117 /** ECDSA_SIG *ECDSA_SIG_new(void)
118  * allocates and initialize a ECDSA_SIG structure
119  * \return pointer to a ECDSA_SIG structure or NULL if an error occurred
120  */
121 ECDSA_SIG *ECDSA_SIG_new(void);
122
123 /** ECDSA_SIG_free
124  * frees a ECDSA_SIG structure
125  * \param a pointer to the ECDSA_SIG structure
126  */
127 void      ECDSA_SIG_free(ECDSA_SIG *a);
128
129 /** i2d_ECDSA_SIG
130  * DER encode content of ECDSA_SIG object (note: this function modifies *pp
131  * (*pp += length of the DER encoded signature)).
132  * \param a  pointer to the ECDSA_SIG object
133  * \param pp pointer to a unsigned char pointer for the output or NULL
134  * \return the length of the DER encoded ECDSA_SIG object or 0 
135  */
136 int       i2d_ECDSA_SIG(const ECDSA_SIG *a, unsigned char **pp);
137
138 /** d2i_ECDSA_SIG
139  * decodes a DER encoded ECDSA signature (note: this function changes *pp
140  * (*pp += len)). 
141  * \param v pointer to ECDSA_SIG pointer (may be NULL)
142  * \param pp buffer with the DER encoded signature
143  * \param len bufferlength
144  * \return pointer to the decoded ECDSA_SIG structure (or NULL)
145  */
146 ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **v, const unsigned char **pp, long len);
147
148 /** ECDSA_DATA_new
149  * creates a new ECDSA_DATA object
150  * \return pointer to a newly allocated (and initialized) ECDSA_DATA object
151  */
152 ECDSA_DATA *ECDSA_DATA_new(void);
153
154 /** ECDSA_DATA_new_method
155  * creates a new ECDSA_DATA object using a specified ENGINE
156  * \param eng pointer to a ENGINE structure
157  * \return pointer to a newly allocated (and initialized) ECDSA_DATA object
158  */
159 ECDSA_DATA *ECDSA_DATA_new_method(ENGINE *eng);
160
161 /** ECDSA_DATA_free
162  * frees ECDSA_DATA structure
163  * \param data pointer to a ECDSA_DATA structure
164  */
165 void ECDSA_DATA_free(ECDSA_DATA *data);
166
167 /** ecdsa_check
168  * checks whether ECKEY->meth_data is a pointer to a ECDSA_DATA structure
169  * and if not it removes the old meth_data and creates a ECDSA_DATA structure.
170  * \param  eckey pointer to a EC_KEY object
171  * \return pointer to a ECDSA_DATA structure
172  */
173 ECDSA_DATA *ecdsa_check(EC_KEY *eckey);
174
175 /** ECDSA_do_sign
176  * computes the ECDSA signature of the given hash value using
177  * the supplied private key and returns the created signature.
178  * \param dgst pointer to the hash value
179  * \param dgst_len length of the hash value
180  * \param eckey pointer to the EC_KEY object containing a private EC key
181  * \return pointer to a ECDSA_SIG structure or NULL
182  */
183 ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst,int dgst_len,EC_KEY *eckey);
184
185 /** ECDSA_do_verify
186  * verifies that the supplied signature is a valid ECDSA
187  * signature of the supplied hash value using the supplied public key.
188  * \param dgst pointer to the hash value
189  * \param dgst_len length of the hash value
190  * \param sig  pointer to the ECDSA_SIG structure
191  * \param eckey pointer to the EC_KEY object containing a public EC key
192  * \return 1 if the signature is valid, 0 if the signature is invalid and -1 on error
193  */
194 int       ECDSA_do_verify(const unsigned char *dgst, int dgst_len,
195                 const ECDSA_SIG *sig, EC_KEY* eckey);
196
197 const ECDSA_METHOD *ECDSA_OpenSSL(void);
198
199 /** ECDSA_set_default_method
200  * sets the default ECDSA method
201  * \param meth the new default ECDSA_METHOD
202  */
203 void      ECDSA_set_default_method(const ECDSA_METHOD *meth);
204
205 /** ECDSA_get_default_method
206  * returns the default ECDSA method
207  * \return pointer to ECDSA_METHOD structure containing the default method
208  */
209 const ECDSA_METHOD *ECDSA_get_default_method(void);
210
211 /** ECDSA_set_method
212  * sets method to be used for the ECDSA operations
213  * \param eckey pointer to the EC_KEY object
214  * \param meth  pointer to the new method
215  * \return 1 on success and 0 otherwise 
216  */
217 int       ECDSA_set_method(EC_KEY *eckey, const ECDSA_METHOD *meth);
218
219 /** ECDSA_size
220  * returns the maximum length of the DER encoded signature
221  * \param  eckey pointer to a EC_KEY object
222  * \return numbers of bytes required for the DER encoded signature
223  */
224 int       ECDSA_size(const EC_KEY *eckey);
225
226 /** ECDSA_sign_setup
227  * precompute parts of the signing operation (the computed values may be
228  * passed to ECDSA_DATA->kinv and ECDSA_DATA->r for a later signature
229  * computation).
230  * \param eckey pointer to the EC_KEY object containing a private EC key
231  * \param ctx  pointer to a BN_CTX object (may be NULL)
232  * \param kinv pointer to a BIGNUM pointer for the inverse of k
233  * \param rp   pointer to a BIGNUM pointer for x coordinate of k * generator
234  * \return 1 on success and 0 otherwise
235  */
236 int       ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, 
237                 BIGNUM **rp);
238
239 /** ECDSA_sign
240  * computes ECDSA signature of a given hash value using the supplied
241  * private key (note: sig must point to ECDSA_size(eckey) bytes of memory).
242  * \param type this parameter is ignored
243  * \param dgst pointer to the hash value to sign
244  * \param dgstlen length of the hash value
245  * \param sig buffer to hold the DER encoded signature
246  * \param siglen pointer to the length of the returned signature
247  * \param eckey pointer to the EC_KEY object containing a private EC key
248  * \return 1 on success and 0 otherwise
249  */
250 int       ECDSA_sign(int type, const unsigned char *dgst, int dgstlen, 
251                 unsigned char *sig, unsigned int *siglen, EC_KEY *eckey);
252
253 /** ECDSA_verify
254  * verifies that the given signature is valid ECDSA signature
255  * of the supplied hash value using the specified public key.
256  * \param type this parameter is ignored
257  * \param dgst pointer to the hash value 
258  * \param dgstlen length of the hash value
259  * \param sig  pointer to the DER encoded signature
260  * \param siglen length of the DER encoded signature
261  * \param eckey pointer to the EC_KEY object containing a public EC key
262  * \return 1 if the signature is valid, 0 if the signature is invalid and -1 on error
263  */
264 int       ECDSA_verify(int type, const unsigned char *dgst, int dgstlen, 
265                 const unsigned char *sig, int siglen, EC_KEY *eckey);
266
267 /* the standard ex_data functions */
268 int       ECDSA_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new 
269                 *new_func, CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
270 int       ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg);
271 void      *ECDSA_get_ex_data(EC_KEY *d, int idx);
272
273
274 /* BEGIN ERROR CODES */
275 /* The following lines are auto generated by the script mkerr.pl. Any changes
276  * made after this point may be overwritten when the script is next run.
277  */
278 void ERR_load_ECDSA_strings(void);
279
280 /* Error codes for the ECDSA functions. */
281
282 /* Function codes. */
283 #define ECDSA_F_ECDSA_DATA_NEW                           100
284 #define ECDSA_F_ECDSA_DO_SIGN                            101
285 #define ECDSA_F_ECDSA_DO_VERIFY                          102
286 #define ECDSA_F_ECDSA_SIGN_SETUP                         103
287
288 /* Reason codes. */
289 #define ECDSA_R_BAD_SIGNATURE                            100
290 #define ECDSA_R_DATA_TOO_LARGE_FOR_KEY_SIZE              101
291 #define ECDSA_R_ERR_EC_LIB                               102
292 #define ECDSA_R_MISSING_PARAMETERS                       103
293 #define ECDSA_R_RANDOM_NUMBER_GENERATION_FAILED          104
294 #define ECDSA_R_SIGNATURE_MALLOC_FAILED                  105
295
296 #ifdef  __cplusplus
297 }
298 #endif
299 #endif