PageRenderTime 25ms CodeModel.GetById 10ms app.highlight 6ms RepoModel.GetById 2ms app.codeStats 0ms

/security/nss/lib/freebl/ecl/README

http://github.com/zpao/v8monkey
#! | 330 lines | 248 code | 82 blank | 0 comment | 0 complexity | 9cda4e12e40e17bf74a682a09be5a207 MD5 | raw file
  1***** BEGIN LICENSE BLOCK *****
  2Version: MPL 1.1/GPL 2.0/LGPL 2.1
  3
  4The contents of this file are subject to the Mozilla Public License Version
  51.1 (the "License"); you may not use this file except in compliance with
  6the License. You may obtain a copy of the License at
  7http://www.mozilla.org/MPL/
  8
  9Software distributed under the License is distributed on an "AS IS" basis,
 10WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 11for the specific language governing rights and limitations under the
 12License.
 13
 14The Original Code is the elliptic curve math library.
 15
 16The Initial Developer of the Original Code is Sun Microsystems, Inc.
 17Portions created by Sun Microsystems, Inc. are Copyright (C) 2003
 18Sun Microsystems, Inc. All Rights Reserved.
 19
 20Contributor(s):
 21    Stephen Fung <fungstep@hotmail.com> and
 22    Douglas Stebila <douglas@stebila.ca>, Sun Microsystems Laboratories
 23
 24Alternatively, the contents of this file may be used under the terms of
 25either the GNU General Public License Version 2 or later (the "GPL"), or
 26the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 27in which case the provisions of the GPL or the LGPL are applicable instead
 28of those above. If you wish to allow use of your version of this file only
 29under the terms of either the GPL or the LGPL, and not to allow others to
 30use your version of this file under the terms of the MPL, indicate your
 31decision by deleting the provisions above and replace them with the notice
 32and other provisions required by the GPL or the LGPL. If you do not delete
 33the provisions above, a recipient may use your version of this file under
 34the terms of any one of the MPL, the GPL or the LGPL.
 35
 36***** END LICENSE BLOCK *****
 37 
 38The ECL exposes routines for constructing and converting curve
 39parameters for internal use.
 40
 41
 42HEADER FILES
 43============
 44
 45ecl-exp.h - Exports data structures and curve names. For use by code
 46that does not have access to mp_ints.
 47
 48ecl-curve.h - Provides hex encodings (in the form of ECCurveParams
 49structs) of standardizes elliptic curve domain parameters and mappings
 50from ECCurveName to ECCurveParams. For use by code that does not have
 51access to mp_ints.
 52
 53ecl.h - Interface to constructors for curve parameters and group object,
 54and point multiplication operations. Used by higher level algorithms
 55(like ECDH and ECDSA) to actually perform elliptic curve cryptography.
 56
 57ecl-priv.h - Data structures and functions for internal use within the
 58library.
 59
 60ec2.h - Internal header file that contains all functions for point
 61arithmetic over binary polynomial fields.
 62
 63ecp.h - Internal header file that contains all functions for point
 64arithmetic over prime fields.
 65
 66DATA STRUCTURES AND TYPES
 67=========================
 68
 69ECCurveName (from ecl-exp.h) - Opaque name for standardized elliptic
 70curve domain parameters.
 71
 72ECCurveParams (from ecl-exp.h) - Provides hexadecimal encoding
 73of elliptic curve domain parameters. Can be generated by a user
 74and passed to ECGroup_fromHex or can be generated from a name by
 75EC_GetNamedCurveParams. ecl-curve.h contains ECCurveParams structs for
 76the standardized curves defined by ECCurveName.
 77
 78ECGroup (from ecl.h and ecl-priv.h) - Opaque data structure that
 79represents a group of elliptic curve points for a particular set of
 80elliptic curve domain parameters. Contains all domain parameters (curve
 81a and b, field, base point) as well as pointers to the functions that
 82should be used for point arithmetic and the underlying field GFMethod.
 83Generated by either ECGroup_fromHex or ECGroup_fromName.
 84
 85GFMethod (from ecl-priv.h) - Represents a field underlying a set of
 86elliptic curve domain parameters. Contains the irreducible that defines
 87the field (either the prime or the binary polynomial) as well as
 88pointers to the functions that should be used for field arithmetic.
 89
 90ARITHMETIC FUNCTIONS
 91====================
 92
 93Higher-level algorithms (like ECDH and ECDSA) should call ECPoint_mul
 94or ECPoints_mul (from ecl.h) to do point arithmetic. These functions
 95will choose which underlying algorithms to use, based on the ECGroup
 96structure.
 97
 98Point Multiplication
 99--------------------
100
101ecl_mult.c provides the ECPoints_mul and ECPoint_mul wrappers.
102It also provides two implementations for the pts_mul operation -
103ec_pts_mul_basic (which computes kP, lQ, and then adds kP + lQ) and
104ec_pts_mul_simul_w2 (which does a simultaneous point multiplication
105using a table with window size 2*2).
106
107ec_naf.c provides an implementation of an algorithm to calculate a
108non-adjacent form of a scalar, minimizing the number of point
109additions that need to be done in a point multiplication.
110
111Point Arithmetic over Prime Fields
112----------------------------------
113
114ecp_aff.c provides point arithmetic using affine coordinates.
115
116ecp_jac.c provides point arithmetic using Jacobian projective
117coordinates and mixed Jacobian-affine coordinates. (Jacobian projective
118coordinates represent a point (x, y) as (X, Y, Z), where x=X/Z^2,
119y=Y/Z^3).
120
121ecp_jm.c provides point arithmetic using Modified Jacobian
122coordinates and mixed Modified_Jacobian-affine coordinates.
123(Modified Jacobian coordinates represent a point (x, y)
124as (X, Y, Z, a*Z^4), where x=X/Z^2, y=Y/Z^3, and a is
125the linear coefficient in the curve defining equation).
126
127ecp_192.c and ecp_224.c provide optimized field arithmetic.
128
129Point Arithmetic over Binary Polynomial Fields
130----------------------------------------------
131
132ec2_aff.c provides point arithmetic using affine coordinates.
133
134ec2_proj.c provides point arithmetic using projective coordinates.
135(Projective coordinates represent a point (x, y) as (X, Y, Z), where
136x=X/Z, y=Y/Z^2).
137
138ec2_mont.c provides point multiplication using Montgomery projective
139coordinates.
140
141ec2_163.c, ec2_193.c, and ec2_233.c provide optimized field arithmetic.
142
143Field Arithmetic
144----------------
145
146ecl_gf.c provides constructors for field objects (GFMethod) with the
147functions GFMethod_cons*. It also provides wrappers around the basic
148field operations.
149
150Prime Field Arithmetic
151----------------------
152
153The mpi library provides the basic prime field arithmetic.
154
155ecp_mont.c provides wrappers around the Montgomery multiplication
156functions from the mpi library and adds encoding and decoding functions.
157It also provides the function to construct a GFMethod object using
158Montgomery multiplication.
159
160ecp_192.c and ecp_224.c provide optimized modular reduction for the
161fields defined by nistp192 and nistp224 primes.
162
163ecl_gf.c provides wrappers around the basic field operations.
164
165Binary Polynomial Field Arithmetic
166----------------------------------
167
168../mpi/mp_gf2m.c provides basic binary polynomial field arithmetic,
169including addition, multiplication, squaring, mod, and division, as well
170as conversion ob polynomial representations between bitstring and int[].
171
172ec2_163.c, ec2_193.c, and ec2_233.c provide optimized field mod, mul,
173and sqr operations.
174
175ecl_gf.c provides wrappers around the basic field operations.
176
177Field Encoding
178--------------
179
180By default, field elements are encoded in their basic form. It is
181possible to use an alternative encoding, however. For example, it is
182possible to Montgomery representation of prime field elements and
183take advantage of the fast modular multiplication that Montgomery
184representation provides. The process of converting from basic form to
185Montgomery representation is called field encoding, and the opposite
186process would be field decoding. All internal point operations assume
187that the operands are field encoded as appropriate. By rewiring the
188underlying field arithmetic to perform operations on these encoded
189values, the same overlying point arithmetic operations can be used
190regardless of field representation.
191
192ALGORITHM WIRING
193================
194
195The EC library allows point and field arithmetic algorithms to be
196substituted ("wired-in") on a fine-grained basis. This allows for
197generic algorithms and algorithms that are optimized for a particular
198curve, field, or architecture, to coexist and to be automatically
199selected at runtime.
200
201Wiring Mechanism
202----------------
203
204The ECGroup and GFMethod structure contain pointers to the point and
205field arithmetic functions, respectively, that are to be used in
206operations.
207
208The selection of algorithms to use is handled in the function
209ecgroup_fromNameAndHex in ecl.c.
210
211Default Wiring
212--------------
213
214Curves over prime fields by default use montgomery field arithmetic,
215point multiplication using 5-bit window non-adjacent-form with 
216Modified Jacobian coordinates, and 2*2-bit simultaneous point 
217multiplication using Jacobian coordinates.
218(Wiring in function ECGroup_consGFp_mont in ecl.c.)
219
220Curves over prime fields that have optimized modular reduction (i.e.,
221secp160r1, nistp192, and nistp224) do not use Montgomery field
222arithmetic. Instead, they use basic field arithmetic with their
223optimized reduction (as in ecp_192.c and ecp_224.c). They
224use the same point multiplication and simultaneous point multiplication
225algorithms as other curves over prime fields.
226
227Curves over binary polynomial fields by default use generic field
228arithmetic with montgomery point multiplication and basic kP + lQ
229computation (multiply, multiply, and add). (Wiring in function
230ECGroup_cons_GF2m in ecl.c.)
231
232Curves over binary polynomial fields that have optimized field
233arithmetic (i.e., any 163-, 193, or 233-bit field) use their optimized
234field arithmetic. They use the same point multiplication and
235simultaneous point multiplication algorithms as other curves over binary
236fields.
237
238Example
239-------
240
241We provide an example for plugging in an optimized implementation for
242the Koblitz curve nistk163.
243
244Suppose the file ec2_k163.c contains the optimized implementation. In
245particular it contains a point multiplication function:
246
247	mp_err ec_GF2m_nistk163_pt_mul(const mp_int *n, const mp_int *px, 
248		const mp_int *py, mp_int *rx, mp_int *ry, const ECGroup *group);
249
250Since only a pt_mul function is provided, the generic pt_add function
251will be used.
252
253There are two options for handling the optimized field arithmetic used
254by the ..._pt_mul function. Say the optimized field arithmetic includes
255the following functions:
256
257	mp_err ec_GF2m_nistk163_add(const mp_int *a, const mp_int *b,
258		mp_int *r, const GFMethod *meth);
259	mp_err ec_GF2m_nistk163_mul(const mp_int *a, const mp_int *b,
260		mp_int *r, const GFMethod *meth);
261	mp_err ec_GF2m_nistk163_sqr(const mp_int *a, const mp_int *b,
262		mp_int *r, const GFMethod *meth);
263	mp_err ec_GF2m_nistk163_div(const mp_int *a, const mp_int *b,
264		mp_int *r, const GFMethod *meth);
265
266First, the optimized field arithmetic could simply be called directly
267by the ..._pt_mul function. This would be accomplished by changing
268the ecgroup_fromNameAndHex function in ecl.c to include the following
269statements:
270
271	if (name == ECCurve_NIST_K163) {
272		group = ECGroup_consGF2m(&irr, NULL, &curvea, &curveb, &genx,
273			&geny, &order, params->cofactor);
274		if (group == NULL) { res = MP_UNDEF; goto CLEANUP; }
275		MP_CHECKOK( ec_group_set_nistk163(group) );
276	}
277
278and including in ec2_k163.c the following function:
279
280	mp_err ec_group_set_nistk163(ECGroup *group) {
281		group->point_mul = &ec_GF2m_nistk163_pt_mul;
282		return MP_OKAY;
283	}
284
285As a result, ec_GF2m_pt_add and similar functions would use the
286basic binary polynomial field arithmetic ec_GF2m_add, ec_GF2m_mul,
287ec_GF2m_sqr, and ec_GF2m_div.
288
289Alternatively, the optimized field arithmetic could be wired into the
290group's GFMethod. This would be accomplished by putting the following
291function in ec2_k163.c:
292
293	mp_err ec_group_set_nistk163(ECGroup *group) {
294		group->meth->field_add = &ec_GF2m_nistk163_add;
295		group->meth->field_mul = &ec_GF2m_nistk163_mul;
296		group->meth->field_sqr = &ec_GF2m_nistk163_sqr;
297		group->meth->field_div = &ec_GF2m_nistk163_div;
298		group->point_mul = &ec_GF2m_nistk163_pt_mul;
299		return MP_OKAY;
300	}
301
302For an example of functions that use special field encodings, take a
303look at ecp_mont.c.
304
305TESTING
306=======
307
308The ecl/tests directory contains a collection of standalone tests that
309verify the correctness of the elliptic curve library.
310
311Both ecp_test and ec2_test take the following arguments:
312
313	--print     Print out results of each point arithmetic test.
314	--time      Benchmark point operations and print results.
315
316The set of curves over which ecp_test and ec2_test run is coded into the
317program, but can be changed by editing the source files.
318
319BUILDING
320========
321
322The ecl can be built as a standalone library, separate from NSS,
323dependent only on the mpi library. To build the library:
324
325	> cd ../mpi
326	> make libs
327	> cd ../ecl
328	> make libs
329	> make tests # to build test files
330	> make test  # to run automated tests