OSX/libsecurity_cryptkit/lib/curveParams.h

   1 /* Copyright (c) 1998,2011-2012,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  * curveParams.h - FEE curve parameter functions
  12  *
  13  * Revision History
  14  * ----------------
  15  *  9 Sep 98 at NeXT
  16  *      Added y1Plus for IEEE P1363 compliance.
  17  *  20 Jan 98 at Apple
  18  *      Added primeType, m, basePrimeRecip.
  19  *  11 Jun 97 at Apple
  20  *      Added x1OrderPlusRecip and lesserX1OrderRecip
  21  *      Disabled CP_SET_GIANT_SIZE hack
  22  *  9 Jan 1997 at NeXT
  23  *      Major mods for IEEE-style parameters.
  24  *  7 Aug 1996 at NeXT
  25  *      Created.
  26  */
  27
  28 #ifndef _CK_CURVEPARAMS_H_
  29 #define _CK_CURVEPARAMS_H_
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 #include "giantIntegers.h"
  36 #include "feeTypes.h"
  37
  38 /*
  39  * Parameters defining a specific elliptic curve (and its initial points).
  40  */
  41 typedef struct {
  42
  43         /*
  44          * Basic characteristic of prime field (PT_FEE, etc.)
  45          */
  46         feePrimeType    primeType;
  47
  48         /*
  49          * Basic curve type (CT_MONTGOMERY, etc.)
  50          * Note that FCT_ANSI is stored here as FCT_Weierstrass.
  51          */
  52         feeCurveType    curveType;
  53
  54         /*
  55          * Parameters defining the base prime (2^q - k) for
  56          * FPT_FEE and FPT_Mersenne. For FPT_General, q is the
  57          * prime size in bits and k is 0.
  58          */
  59         unsigned        q;
  60         int         k;
  61
  62         /*
  63          * For all primeTypes, the field is defined as F(basePrime**m).
  64          * This library can only deal with m == 1 for now.
  65          */
  66         unsigned        m;
  67
  68         /*
  69          * coefficients in the following equation:
  70          * y^2 = x^3 + (c * x^2) + (a * x) + b
  71          */
  72         giant           a;
  73         giant           b;
  74         giant           c;
  75
  76         /*
  77          * Initial public point x-coordinates.
  78          * x1Minus not used for ECDSA; X9.62 curves don't have this field.
  79          */
  80         giant           x1Plus;
  81         giant           x1Minus;
  82
  83         /*
  84          * Y coordinate of normalized projective initial public
  85          * point for plus curve. I.e., Initial point = {x1Plus, p1Plus, 1}.
  86          * Only valid for curveType == CT_WEIERSTRASS. This is calculated
  87          * when a new curveParams is created.
  88          */
  89         giant           y1Plus;
  90
  91         /*
  92          * Curve orders. These are prime, or have large prime factors.
  93          * cOrderMinus not used for ECDSA; X9.62 curves don't have this field.
  94          */
  95         giant           cOrderPlus;
  96         giant           cOrderMinus;
  97
  98         /*
  99          * Point orders (the large prime factors of the respective
 100          * curve orders).
 101          * x1OrderMinus not used for ECDSA; X9.62 curves don't have this field.
 102          */
 103         giant           x1OrderPlus;
 104         giant           x1OrderMinus;
 105
 106         /*
 107          * The base prime. For PT_GENERAL, this is a basic defining
 108          * characteristic of a curve; otherwise, it is derived as 2**q - k.
 109          */
 110         giant           basePrime;
 111
 112         /*
 113          * The remaining fields are calculated and stored here as an
 114          * optimization.
 115          */
 116
 117         /*
 118          * The minimum size of a giant, in bytes, to represent any point
 119          * on this curve. This is generally used only when serializing
 120          * giants of a known size.
 121          */
 122         unsigned        minBytes;
 123
 124         /*
 125          * The maximum size of a giant, in giantDigits, to be used with all
 126          * FEE arithmetic for this curve. This is generally used to alloc
 127          * giants.
 128          */
 129         unsigned        maxDigits;
 130
 131         /*
 132          * Reciprocals of lesserX1Order() and x1OrderPlus. Calculated
 133          * lazily by clients in the case of creation of a curveParams
 134          * struct from a byteRep representation.
 135          */
 136         giant           x1OrderPlusRecip;
 137         giant           lesserX1OrderRecip;
 138
 139         /*
 140          * Reciprocal of basePrime. Only used for PT_GENERAL.
 141          */
 142         giant           basePrimeRecip;
 143 } curveParams;
 144
 145 #if 0
 146 /*
 147  * Values for primeType.
 148  */
 149 #define PT_MERSENNE     0       /* basePrime = 2**q - 1 */
 150 #define PT_FEE          1       /* basePrime = 2**q - k, k is "small" */
 151 #define PT_GENERAL      2       /* other prime modulus */
 152
 153 /*
 154  * Values for curveType. Note that Atkin3 (a=0) and Atkin4 (b=0) are
 155  * subsets of CT_WEIERSTRASS.
 156  */
 157 #define CT_MONTGOMERY   0       /* a=1, b=0 */
 158 #define CT_WEIERSTRASS  1       /* c=0 */
 159 #define CT_GENERAL              4       /* other */
 160 #endif /* 0 */
 161
 162 /*
 163  * Obtain a malloc'd curveParams for a specified feeDepth.
 164  */
 165 curveParams *curveParamsForDepth(feeDepth depth);
 166
 167 /*
 168  * Obtain a malloc'd and uninitialized curveParams, to be init'd by caller
 169  * (when matching existing curve params).
 170  */
 171 curveParams *newCurveParams(void);
 172
 173 /*
 174  * Alloc and zero reciprocal giants, when maxDigits is known.
 175  */
 176 void allocRecipGiants(curveParams *cp);
 177
 178 /*
 179  * Alloc a new curveParams struct as a copy of specified instance.
 180  */
 181 curveParams *curveParamsCopy(curveParams *cp);
 182
 183 /*
 184  * Free a curveParams struct.
 185  */
 186 void freeCurveParams(curveParams *cp);
 187
 188 /*
 189  * Returns 1 if two sets of curve parameters are equivalent, else returns 0.
 190  */
 191 int curveParamsEquivalent(curveParams *cp1, curveParams *cp2);
 192
 193 /*
 194  * Obtain the lesser of {x1OrderPlus, x1OrderMinus}. Returned value is not
 195  * malloc'd; it's a pointer to one of the orders in *cp.
 196  */
 197 giant lesserX1Order(curveParams *cp);
 198
 199 /*
 200  * Prime the curveParams and giants modules for quick allocs of giants.
 201  */
 202 void curveParamsInitGiants(void);
 203
 204 /*
 205  * Infer run-time calculated fields from a partially constructed curveParams.
 206  */
 207 void curveParamsInferFields(curveParams *cp);
 208
 209 /*
 210  * Given key size in bits, obtain the asssociated depth.
 211  * Returns FR_IllegalDepth if specify key size not found
 212  * in current curve tables.
 213  */
 214 feeReturn feeKeyBitsToDepth(unsigned keyBits,
 215         feePrimeType primeType,         /* FPT_Fefault means "best one" */
 216         feeCurveType curveType,         /* FCT_Default means "best one" */
 217         feeDepth *depth);
 218
 219 /*
 220  * Obtain depth for specified curveParams
 221  */
 222 feeReturn curveParamsDepth(
 223         curveParams *cp,
 224         feeDepth *depth);
 225
 226 #ifdef __cplusplus
 227 }
 228 #endif
 229
 230 #endif  /* _CK_CURVEPARAMS_H_ */