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
29extern "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
38typedef 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
55typedef 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
64key new_public(curveParams *cp, int twist);
65
66/*
67 * Specify private data for key created by new_public().
68 * Generates k->x.
69 */
70void set_priv_key_giant(key k, giant privGiant);
71
72/*
73 * Generate new key with twist and k->x from old_key.
74 */
75key 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 */
80int key_equal(key first, key second);
81
82/*
83 * De-allocate an allocated key.
84 */
85void 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 */
93void 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 */
105void elliptic_simple(giant x, giant n, curveParams *par);
106
107/*
108 * General elliptic multiply: {xx, zz} := k * {xx, zz}
109 */
110void 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 */
116int which_curve(giant x, curveParams *par);
117
118/*
119 * Generate (2**q)-k.
120 */
121void make_base_prim(curveParams *cp);
122
123/*
124 * return a new giant that is the pad from private data and public key
125 */
126giant 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 */
132int 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 */
138void curveOrderJustify(giant g, giant curveOrder);
139
140void lesserX1OrderJustify(giant g, curveParams *cp);
141void x1OrderPlusJustify(giant g, curveParams *cp);
142void x1OrderPlusMod(giant g, curveParams *cp);
143
144void calcX1OrderPlusRecip(curveParams *cp);
145
146/*
147 * x := x mod basePrime.
148 */
149void feemod(curveParams *par, giant x);
150
151/*
152 * For a given curveParams, calculate minBytes and maxDigits.
153 */
154void calcGiantSizes(curveParams *cp);
155unsigned giantMinBytes(unsigned q, int k);
156unsigned giantMaxDigits(unsigned minBytes);
157
158int binvg_cp(curveParams *cp, giant x);
159int binvg_x1OrderPlus(curveParams *cp, giant x);
160
161#ifdef __cplusplus
162}
163#endif
164
165#endif	/*_CK_NSFEE_H_*/
166