ecc.h

00001 /* ecc.h
00002  *
00003  * Copyright (C) 2006-2016 wolfSSL Inc.
00004  *
00005  * This file is part of wolfSSL.
00006  *
00007  * wolfSSL is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 2 of the License, or
00010  * (at your option) any later version.
00011  *
00012  * wolfSSL is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  *
00017  * You should have received a copy of the GNU General Public License
00018  * along with this program; if not, write to the Free Software
00019  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
00020  */
00021 
00022 
00023 #ifndef WOLF_CRYPT_ECC_H
00024 #define WOLF_CRYPT_ECC_H
00025 
00026 #include <wolfssl/wolfcrypt/types.h>
00027 
00028 #ifdef HAVE_ECC
00029 
00030 #include <wolfssl/wolfcrypt/integer.h>
00031 #include <wolfssl/wolfcrypt/random.h>
00032 
00033 #ifdef __cplusplus
00034     extern "C" {
00035 #endif
00036 
00037 enum {
00038     ECC_PUBLICKEY   = 1,
00039     ECC_PRIVATEKEY  = 2,
00040     ECC_MAXNAME     = 16,   /* MAX CURVE NAME LENGTH */
00041     SIG_HEADER_SZ   =  6,   /* ECC signature header size */
00042     ECC_BUFSIZE     = 256,  /* for exported keys temp buffer */
00043     ECC_MINSIZE     = 20,   /* MIN Private Key size */
00044     ECC_MAXSIZE     = 66,   /* MAX Private Key size */
00045     ECC_MAXSIZE_GEN = 74,   /* MAX Buffer size required when generating ECC keys*/
00046     ECC_MAX_PAD_SZ  = 4     /* ECC maximum padding size */
00047 };
00048 
00049 
00050 /* ECC set type defined a NIST GF(p) curve */
00051 typedef struct {
00052     int size;             /* The size of the curve in octets */
00053     int nid;              /* id of this curve */
00054     const char* name;     /* name of this curve */
00055     const char* prime;    /* prime that defines the field, curve is in (hex) */
00056     const char* Af;       /* fields A param (hex) */
00057     const char* Bf;       /* fields B param (hex) */
00058     const char* order;    /* order of the curve (hex) */
00059     const char* Gx;       /* x coordinate of the base point on curve (hex) */
00060     const char* Gy;       /* y coordinate of the base point on curve (hex) */
00061 } ecc_set_type;
00062 
00063 
00064 #ifdef ALT_ECC_SIZE
00065 
00066 /* Note on ALT_ECC_SIZE:
00067  * The fast math code uses an array of a fixed size to store the big integers.
00068  * By default, the array is big enough for RSA keys. There is a size,
00069  * FP_MAX_BITS which can be used to make the array smaller when one wants ECC
00070  * but not RSA. Some people want fast math sized for both RSA and ECC, where
00071  * ECC won't use as much as RSA. The flag ALT_ECC_SIZE switches in an alternate
00072  * ecc_point structure that uses an alternate fp_int that has a shorter array
00073  * of fp_digits.
00074  *
00075  * Now, without ALT_ECC_SIZE, the ecc_point has three single item arrays of
00076  * mp_ints for the components of the point. With ALT_ECC_SIZE, the components
00077  * of the point are pointers that are set to each of a three item array of
00078  * alt_fp_ints. While an mp_int will have 4096 bits of digit inside the
00079  * structure, the alt_fp_int will only have 528 bits. A size value was added
00080  * in the ALT case, as well, and is set by mp_init() and alt_fp_init(). The
00081  * functions fp_zero() and fp_copy() use the size parameter. An int needs to
00082  * be initialized before using it instead of just fp_zeroing it, the init will
00083  * call zero. FP_MAX_BITS_ECC defaults to 528, but can be set to change the
00084  * number of bits used in the alternate FP_INT.
00085  *
00086  * Do not enable ALT_ECC_SIZE and disable fast math in the configuration.
00087  */
00088 
00089 #ifndef USE_FAST_MATH
00090     #error USE_FAST_MATH must be defined to use ALT_ECC_SIZE
00091 #endif
00092 
00093 #ifndef FP_MAX_BITS_ECC
00094     #define FP_MAX_BITS_ECC           528
00095 #endif
00096 #define FP_MAX_SIZE_ECC           (FP_MAX_BITS_ECC+(8*DIGIT_BIT))
00097 #if FP_MAX_BITS_ECC % CHAR_BIT
00098    #error FP_MAX_BITS_ECC must be a multiple of CHAR_BIT
00099 #endif
00100 #define FP_SIZE_ECC    (FP_MAX_SIZE_ECC/DIGIT_BIT)
00101 
00102 /* This needs to match the size of the fp_int struct, except the
00103  * fp_digit array will be shorter. */
00104 typedef struct alt_fp_int {
00105     int used, sign, size;
00106     fp_digit dp[FP_SIZE_ECC];
00107 } alt_fp_int;
00108 #endif
00109 
00110 /* A point on an ECC curve, stored in Jacbobian format such that (x,y,z) =>
00111    (x/z^2, y/z^3, 1) when interpreted as affine */
00112 typedef struct {
00113 #ifndef ALT_ECC_SIZE
00114     mp_int x[1];        /* The x coordinate */
00115     mp_int y[1];        /* The y coordinate */
00116     mp_int z[1];        /* The z coordinate */
00117 #else
00118     mp_int* x;        /* The x coordinate */
00119     mp_int* y;        /* The y coordinate */
00120     mp_int* z;        /* The z coordinate */
00121     alt_fp_int xyz[3];
00122 #endif
00123 } ecc_point;
00124 
00125 
00126 /* An ECC Key */
00127 typedef struct {
00128     int type;           /* Public or Private */
00129     int idx;            /* Index into the ecc_sets[] for the parameters of
00130                            this curve if -1, this key is using user supplied
00131                            curve in dp */
00132     const ecc_set_type* dp;     /* domain parameters, either points to NIST
00133                                    curves (idx >= 0) or user supplied */
00134     ecc_point pubkey;   /* public key */
00135     mp_int    k;        /* private key */
00136 } ecc_key;
00137 
00138 
00139 /* ECC predefined curve sets  */
00140 extern const ecc_set_type ecc_sets[];
00141 
00142 
00143 WOLFSSL_API
00144 int wc_ecc_make_key(WC_RNG* rng, int keysize, ecc_key* key);
00145 WOLFSSL_API
00146 int wc_ecc_check_key(ecc_key* key);
00147 
00148 #ifdef HAVE_ECC_DHE
00149 WOLFSSL_API
00150 int wc_ecc_shared_secret(ecc_key* private_key, ecc_key* public_key, byte* out,
00151                       word32* outlen);
00152 WOLFSSL_API
00153 int wc_ecc_shared_secret_ssh(ecc_key* private_key, ecc_point* point,
00154                              byte* out, word32 *outlen);
00155 #endif /* HAVE_ECC_DHE */
00156 
00157 #ifdef HAVE_ECC_SIGN
00158 WOLFSSL_API
00159 int wc_ecc_sign_hash(const byte* in, word32 inlen, byte* out, word32 *outlen,
00160                      WC_RNG* rng, ecc_key* key);
00161 WOLFSSL_API
00162 int wc_ecc_sign_hash_ex(const byte* in, word32 inlen, WC_RNG* rng,
00163                         ecc_key* key, mp_int *r, mp_int *s);
00164 #endif /* HAVE_ECC_SIGN */
00165 
00166 #ifdef HAVE_ECC_VERIFY
00167 WOLFSSL_API
00168 int wc_ecc_verify_hash(const byte* sig, word32 siglen, const byte* hash,
00169                     word32 hashlen, int* stat, ecc_key* key);
00170 WOLFSSL_API
00171 int wc_ecc_verify_hash_ex(mp_int *r, mp_int *s, const byte* hash,
00172                           word32 hashlen, int* stat, ecc_key* key);
00173 #endif /* HAVE_ECC_VERIFY */
00174 
00175 WOLFSSL_API
00176 int wc_ecc_init(ecc_key* key);
00177 WOLFSSL_API
00178 void wc_ecc_free(ecc_key* key);
00179 WOLFSSL_API
00180 void wc_ecc_fp_free(void);
00181 
00182 WOLFSSL_API
00183 ecc_point* wc_ecc_new_point(void);
00184 WOLFSSL_API
00185 void wc_ecc_del_point(ecc_point* p);
00186 WOLFSSL_API
00187 int wc_ecc_copy_point(ecc_point* p, ecc_point *r);
00188 WOLFSSL_API
00189 int wc_ecc_cmp_point(ecc_point* a, ecc_point *b);
00190 WOLFSSL_API
00191 int wc_ecc_point_is_at_infinity(ecc_point *p);
00192 WOLFSSL_API
00193 int wc_ecc_is_valid_idx(int n);
00194 WOLFSSL_API
00195 int wc_ecc_mulmod(mp_int* k, ecc_point *G, ecc_point *R,
00196                   mp_int* modulus, int map);
00197 
00198 #ifdef HAVE_ECC_KEY_EXPORT
00199 /* ASN key helpers */
00200 WOLFSSL_API
00201 int wc_ecc_export_x963(ecc_key*, byte* out, word32* outLen);
00202 WOLFSSL_API
00203 int wc_ecc_export_x963_ex(ecc_key*, byte* out, word32* outLen, int compressed);
00204     /* extended functionality with compressed option */
00205 #endif /* HAVE_ECC_KEY_EXPORT */
00206 
00207 #ifdef HAVE_ECC_KEY_IMPORT
00208 WOLFSSL_API
00209 int wc_ecc_import_x963(const byte* in, word32 inLen, ecc_key* key);
00210 WOLFSSL_API
00211 int wc_ecc_import_private_key(const byte* priv, word32 privSz, const byte* pub,
00212                            word32 pubSz, ecc_key* key);
00213 WOLFSSL_API
00214 int wc_ecc_rs_to_sig(const char* r, const char* s, byte* out, word32* outlen);
00215 WOLFSSL_API
00216 int wc_ecc_import_raw(ecc_key* key, const char* qx, const char* qy,
00217                    const char* d, const char* curveName);
00218 #endif /* HAVE_ECC_KEY_IMPORT */
00219 
00220 #ifdef HAVE_ECC_KEY_EXPORT
00221 WOLFSSL_API
00222 int wc_ecc_export_private_only(ecc_key* key, byte* out, word32* outLen);
00223 
00224 WOLFSSL_API
00225 int wc_ecc_export_point_der(const int curve_idx, ecc_point* point,
00226                             byte* out, word32* outLen);
00227 #endif /* HAVE_ECC_KEY_EXPORT */
00228 
00229 #ifdef HAVE_ECC_KEY_IMPORT
00230 WOLFSSL_API
00231 int wc_ecc_import_point_der(byte* in, word32 inLen, const int curve_idx,
00232                             ecc_point* point);
00233 #endif /* HAVE_ECC_KEY_IMPORT */
00234 
00235 /* size helper */
00236 WOLFSSL_API
00237 int wc_ecc_size(ecc_key* key);
00238 WOLFSSL_API
00239 int wc_ecc_sig_size(ecc_key* key);
00240 
00241 
00242 #ifdef HAVE_ECC_ENCRYPT
00243 /* ecc encrypt */
00244 
00245 enum ecEncAlgo {
00246     ecAES_128_CBC = 1,  /* default */
00247     ecAES_256_CBC = 2
00248 };
00249 
00250 enum ecKdfAlgo {
00251     ecHKDF_SHA256 = 1,  /* default */
00252     ecHKDF_SHA1   = 2
00253 };
00254 
00255 enum ecMacAlgo {
00256     ecHMAC_SHA256 = 1,  /* default */
00257     ecHMAC_SHA1   = 2
00258 };
00259 
00260 enum {
00261     KEY_SIZE_128     = 16,
00262     KEY_SIZE_256     = 32,
00263     IV_SIZE_64       =  8,
00264     IV_SIZE_128      = 16,
00265     EXCHANGE_SALT_SZ = 16,
00266     EXCHANGE_INFO_SZ = 23
00267 };
00268 
00269 enum ecFlags {
00270     REQ_RESP_CLIENT = 1,
00271     REQ_RESP_SERVER = 2
00272 };
00273 
00274 
00275 typedef struct ecEncCtx ecEncCtx;
00276 
00277 WOLFSSL_API
00278 ecEncCtx* wc_ecc_ctx_new(int flags, WC_RNG* rng);
00279 WOLFSSL_API
00280 void wc_ecc_ctx_free(ecEncCtx*);
00281 WOLFSSL_API
00282 int wc_ecc_ctx_reset(ecEncCtx*, WC_RNG*);  /* reset for use again w/o alloc/free */
00283 
00284 WOLFSSL_API
00285 const byte* wc_ecc_ctx_get_own_salt(ecEncCtx*);
00286 WOLFSSL_API
00287 int wc_ecc_ctx_set_peer_salt(ecEncCtx*, const byte* salt);
00288 WOLFSSL_API
00289 int wc_ecc_ctx_set_info(ecEncCtx*, const byte* info, int sz);
00290 
00291 WOLFSSL_API
00292 int wc_ecc_encrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg,
00293                 word32 msgSz, byte* out, word32* outSz, ecEncCtx* ctx);
00294 WOLFSSL_API
00295 int wc_ecc_decrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg,
00296                 word32 msgSz, byte* out, word32* outSz, ecEncCtx* ctx);
00297 
00298 #endif /* HAVE_ECC_ENCRYPT */
00299 
00300 #ifdef __cplusplus
00301     }    /* extern "C" */
00302 #endif
00303 
00304 #endif /* HAVE_ECC */
00305 #endif /* WOLF_CRYPT_ECC_H */
00306