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 32extern "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 */ 41typedef 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 */ 165curveParams *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 */ 171curveParams *newCurveParams(void); 172 173/* 174 * Alloc and zero reciprocal giants, when maxDigits is known. 175 */ 176void allocRecipGiants(curveParams *cp); 177 178/* 179 * Alloc a new curveParams struct as a copy of specified instance. 180 */ 181curveParams *curveParamsCopy(curveParams *cp); 182 183/* 184 * Free a curveParams struct. 185 */ 186void freeCurveParams(curveParams *cp); 187 188/* 189 * Returns 1 if two sets of curve parameters are equivalent, else returns 0. 190 */ 191int 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 */ 197giant lesserX1Order(curveParams *cp); 198 199/* 200 * Prime the curveParams and giants modules for quick allocs of giants. 201 */ 202void curveParamsInitGiants(void); 203 204/* 205 * Infer run-time calculated fields from a partially constructed curveParams. 206 */ 207void 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 */ 214feeReturn 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 */ 222feeReturn curveParamsDepth( 223 curveParams *cp, 224 feeDepth *depth); 225 226#ifdef __cplusplus 227} 228#endif 229 230#endif /* _CK_CURVEPARAMS_H_ */ 231