OSX/libsecurity_cryptkit/lib/elliptic.h

   1 /* Copyright (c) 1998,2011,2014 Apple Inc.  All Rights Reserved.
   2  *
   3  * NOTICE: USE OF THE MATERIALS ACCOMPANYING THIS NOTICE IS SUBJECT
   4  * TO THE TERMS OF THE SIGNED "FAST ELLIPTIC ENCRYPTION (FEE) REFERENCE
   5  * SOURCE CODE EVALUATION AGREEMENT" BETWEEN APPLE, INC. AND THE
   6  * ORIGINAL LICENSEE THAT OBTAINED THESE MATERIALS FROM APPLE,
   7  * INC.  ANY USE OF THESE MATERIALS NOT PERMITTED BY SUCH AGREEMENT WILL
   8  * EXPOSE YOU TO LIABILITY.
   9  ***************************************************************************
  10  *
  11  * elliptic.h - Fast Elliptic Encryption functions.
  12  *
  13  * Revision History
  14  * ----------------
  15  * 10/06/98             ap
  16  *      Changed to compile with C++.
  17  * 19 Feb 97 at NeXT
  18  *      Created.
  19  */
  20
  21 #ifndef _CK_NSFEE_H_
  22 #define _CK_NSFEE_H_
  23
  24 #include "giantIntegers.h"
  25 #include "feeTypes.h"
  26 #include "curveParams.h"
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /*
  33  * Twist, or "which curve", parameter.
  34  */
  35 #define CURVE_PLUS      ((int)1)
  36 #define CURVE_MINUS     ((int)(-1))
  37
  38 typedef struct {
  39         int             twist;                  // CURVE_PLUS or CURVE_MINUS
  40         giant           x;                              // x coord of public key
  41
  42         /*
  43          * only valid for (twist == CURVE_PLUS) and curveType CT_WEIERSTRASS.
  44          * Otherwise it's a zero-value giant.
  45          */
  46         giant           y;                              // y coord of public key
  47
  48         /*
  49          * Note: this module never allocs or frees a curveParams structs.
  50          * This field is always maintained by clients of this module.
  51          */
  52         curveParams     *cp;            // common curve parameters
  53 } keystruct;
  54
  55 typedef keystruct *key;
  56
  57 /*
  58  * Select which curve is the default curve for calculating signatures and
  59  * doing key exchange. This *must* be CURVE_PLUS for key exchange to work
  60  * with ECDSA keys and curves.
  61  */
  62 #define DEFAULT_CURVE   CURVE_PLUS
  63
  64 key new_public(curveParams *cp, int twist);
  65
  66 /*
  67  * Specify private data for key created by new_public().
  68  * Generates k->x.
  69  */
  70 void set_priv_key_giant(key k, giant privGiant);
  71
  72 /*
  73  * Generate new key with twist and k->x from old_key.
  74  */
  75 key new_public_with_key(key old_key, curveParams *cp);
  76
  77 /*
  78  * Returns 1 if all parameters of two keys are equal, else returns 0.
  79  */
  80 int key_equal(key first, key second);
  81
  82 /*
  83  * De-allocate an allocated key.
  84  */
  85 void free_key(key pub);
  86
  87 /*
  88  * x3 = x1 + x2 on the curve, with sign ambiguity s.
  89  *
  90  * Note that int s is not just the twist field, because both s = +-1 must
  91  * be tested in general.
  92  */
  93 void elliptic_add(giant x1, giant x2, giant x3, curveParams *par, int s);
  94
  95 /*
  96  * Values for the 's', or sign, argument to elliptic_add().
  97  */
  98 #define SIGN_PLUS       1
  99 #define SIGN_MINUS      (-1)
 100
 101
 102 /*
 103  * Elliptic multiply: x := n * {x, 1}
 104  */
 105 void elliptic_simple(giant x, giant n, curveParams *par);
 106
 107 /*
 108  * General elliptic multiply: {xx, zz} := k * {xx, zz}
 109  */
 110 void elliptic(giant xx, giant zz, giant k, curveParams *par);
 111
 112 /*
 113  * Returns CURVE_PLUS or CURVE_MINUS, indicating which curve a particular
 114  * x coordinate resides on.
 115  */
 116 int which_curve(giant x, curveParams *par);
 117
 118 /*
 119  * Generate (2**q)-k.
 120  */
 121 void make_base_prim(curveParams *cp);
 122
 123 /*
 124  * return a new giant that is the pad from private data and public key
 125  */
 126 giant make_pad(giant privGiant, key publicKey);
 127
 128 /*
 129  * Returns non-zero if x(p1) cannot be the x-coordinate of the
 130  * sum of two points whose respective x-coordinates are x(p2), x(p3).
 131  */
 132 int signature_compare(giant p0x, giant p1x, giant p2x, curveParams *par);
 133
 134 /*
 135  * Set g := g mod curveOrder;
 136  * force g to be between 2 and (curveOrder-2), inclusive.
 137  */
 138 void curveOrderJustify(giant g, giant curveOrder);
 139
 140 void lesserX1OrderJustify(giant g, curveParams *cp);
 141 void x1OrderPlusJustify(giant g, curveParams *cp);
 142 void x1OrderPlusMod(giant g, curveParams *cp);
 143
 144 void calcX1OrderPlusRecip(curveParams *cp);
 145
 146 /*
 147  * x := x mod basePrime.
 148  */
 149 void feemod(curveParams *par, giant x);
 150
 151 /*
 152  * For a given curveParams, calculate minBytes and maxDigits.
 153  */
 154 void calcGiantSizes(curveParams *cp);
 155 unsigned giantMinBytes(unsigned q, int k);
 156 unsigned giantMaxDigits(unsigned minBytes);
 157
 158 int binvg_cp(curveParams *cp, giant x);
 159 int binvg_x1OrderPlus(curveParams *cp, giant x);
 160
 161 #ifdef __cplusplus
 162 }
 163 #endif
 164
 165 #endif  /*_CK_NSFEE_H_*/