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