nss-3.41/nss/lib/freebl/ecl/README - manifest_repos/nss - Git at Google

 This Source Code Form is subject to the terms of the Mozilla Public
 License, v. 2.0. If a copy of the MPL was not distributed with this
 file, You can obtain one at http://mozilla.org/MPL/2.0/.

 The ECL exposes routines for constructing and converting curve
 parameters for internal use.


 HEADER FILES
 ============

 ecl-exp.h - Exports data structures and curve names. For use by code
 that does not have access to mp_ints.

 ecl-curve.h - Provides hex encodings (in the form of ECCurveParams
 structs) of standardizes elliptic curve domain parameters and mappings
 from ECCurveName to ECCurveParams. For use by code that does not have
 access to mp_ints.

 ecl.h - Interface to constructors for curve parameters and group object,
 and point multiplication operations. Used by higher level algorithms
 (like ECDH and ECDSA) to actually perform elliptic curve cryptography.

 ecl-priv.h - Data structures and functions for internal use within the
 library.

 ecp.h - Internal header file that contains all functions for point
 arithmetic over prime fields.

 DATA STRUCTURES AND TYPES
 =========================

 ECCurveName (from ecl-exp.h) - Opaque name for standardized elliptic
 curve domain parameters.

 ECCurveParams (from ecl-exp.h) - Provides hexadecimal encoding
 of elliptic curve domain parameters. Can be generated by a user
 and passed to ECGroup_fromHex or can be generated from a name by
 EC_GetNamedCurveParams. ecl-curve.h contains ECCurveParams structs for
 the standardized curves defined by ECCurveName.

 ECGroup (from ecl.h and ecl-priv.h) - Opaque data structure that
 represents a group of elliptic curve points for a particular set of
 elliptic curve domain parameters. Contains all domain parameters (curve
 a and b, field, base point) as well as pointers to the functions that
 should be used for point arithmetic and the underlying field GFMethod.
 Generated by either ECGroup_fromHex or ECGroup_fromName.

 GFMethod (from ecl-priv.h) - Represents a field underlying a set of
 elliptic curve domain parameters. Contains the irreducible that defines
 the field (either the prime or the binary polynomial) as well as
 pointers to the functions that should be used for field arithmetic.

 ARITHMETIC FUNCTIONS
 ====================

 Higher-level algorithms (like ECDH and ECDSA) should call ECPoint_mul
 or ECPoints_mul (from ecl.h) to do point arithmetic. These functions
 will choose which underlying algorithms to use, based on the ECGroup
 structure.

 Point Multiplication
 --------------------

 ecl_mult.c provides the ECPoints_mul and ECPoint_mul wrappers.
 It also provides two implementations for the pts_mul operation -
 ec_pts_mul_basic (which computes kP, lQ, and then adds kP + lQ) and
 ec_pts_mul_simul_w2 (which does a simultaneous point multiplication
 using a table with window size 2*2).

 ec_naf.c provides an implementation of an algorithm to calculate a
 non-adjacent form of a scalar, minimizing the number of point
 additions that need to be done in a point multiplication.

 Point Arithmetic over Prime Fields
 ----------------------------------

 ecp_aff.c provides point arithmetic using affine coordinates.

 ecp_jac.c provides point arithmetic using Jacobian projective
 coordinates and mixed Jacobian-affine coordinates. (Jacobian projective
 coordinates represent a point (x, y) as (X, Y, Z), where x=X/Z^2,
 y=Y/Z^3).

 ecp_jm.c provides point arithmetic using Modified Jacobian
 coordinates and mixed Modified_Jacobian-affine coordinates.
 (Modified Jacobian coordinates represent a point (x, y)
 as (X, Y, Z, a*Z^4), where x=X/Z^2, y=Y/Z^3, and a is
 the linear coefficient in the curve defining equation).

 ecp_192.c and ecp_224.c provide optimized field arithmetic.

 Field Arithmetic
 ----------------

 ecl_gf.c provides constructors for field objects (GFMethod) with the
 functions GFMethod_cons*. It also provides wrappers around the basic
 field operations.

 Prime Field Arithmetic
 ----------------------

 The mpi library provides the basic prime field arithmetic.

 ecp_mont.c provides wrappers around the Montgomery multiplication
 functions from the mpi library and adds encoding and decoding functions.
 It also provides the function to construct a GFMethod object using
 Montgomery multiplication.

 ecp_192.c and ecp_224.c provide optimized modular reduction for the
 fields defined by nistp192 and nistp224 primes.

 ecl_gf.c provides wrappers around the basic field operations.

 Field Encoding
 --------------

 By default, field elements are encoded in their basic form. It is
 possible to use an alternative encoding, however. For example, it is
 possible to Montgomery representation of prime field elements and
 take advantage of the fast modular multiplication that Montgomery
 representation provides. The process of converting from basic form to
 Montgomery representation is called field encoding, and the opposite
 process would be field decoding. All internal point operations assume
 that the operands are field encoded as appropriate. By rewiring the
 underlying field arithmetic to perform operations on these encoded
 values, the same overlying point arithmetic operations can be used
 regardless of field representation.

 ALGORITHM WIRING
 ================

 The EC library allows point and field arithmetic algorithms to be
 substituted ("wired-in") on a fine-grained basis. This allows for
 generic algorithms and algorithms that are optimized for a particular
 curve, field, or architecture, to coexist and to be automatically
 selected at runtime.

 Wiring Mechanism
 ----------------

 The ECGroup and GFMethod structure contain pointers to the point and
 field arithmetic functions, respectively, that are to be used in
 operations.

 The selection of algorithms to use is handled in the function
 ecgroup_fromNameAndHex in ecl.c.

 Default Wiring
 --------------

 Curves over prime fields by default use montgomery field arithmetic,
 point multiplication using 5-bit window non-adjacent-form with
 Modified Jacobian coordinates, and 2*2-bit simultaneous point
 multiplication using Jacobian coordinates.
 (Wiring in function ECGroup_consGFp_mont in ecl.c.)

 Curves over prime fields that have optimized modular reduction (i.e.,
 secp160r1, nistp192, and nistp224) do not use Montgomery field
 arithmetic. Instead, they use basic field arithmetic with their
 optimized reduction (as in ecp_192.c and ecp_224.c). They
 use the same point multiplication and simultaneous point multiplication
 algorithms as other curves over prime fields.
	This Source Code Form is subject to the terms of the Mozilla Public
	License, v. 2.0. If a copy of the MPL was not distributed with this
	file, You can obtain one at http://mozilla.org/MPL/2.0/.

	The ECL exposes routines for constructing and converting curve
	parameters for internal use.


	HEADER FILES
	============

	ecl-exp.h - Exports data structures and curve names. For use by code
	that does not have access to mp_ints.

	ecl-curve.h - Provides hex encodings (in the form of ECCurveParams
	structs) of standardizes elliptic curve domain parameters and mappings
	from ECCurveName to ECCurveParams. For use by code that does not have
	access to mp_ints.

	ecl.h - Interface to constructors for curve parameters and group object,
	and point multiplication operations. Used by higher level algorithms
	(like ECDH and ECDSA) to actually perform elliptic curve cryptography.

	ecl-priv.h - Data structures and functions for internal use within the
	library.

	ecp.h - Internal header file that contains all functions for point
	arithmetic over prime fields.

	DATA STRUCTURES AND TYPES
	=========================

	ECCurveName (from ecl-exp.h) - Opaque name for standardized elliptic
	curve domain parameters.

	ECCurveParams (from ecl-exp.h) - Provides hexadecimal encoding
	of elliptic curve domain parameters. Can be generated by a user
	and passed to ECGroup_fromHex or can be generated from a name by
	EC_GetNamedCurveParams. ecl-curve.h contains ECCurveParams structs for
	the standardized curves defined by ECCurveName.

	ECGroup (from ecl.h and ecl-priv.h) - Opaque data structure that
	represents a group of elliptic curve points for a particular set of
	elliptic curve domain parameters. Contains all domain parameters (curve
	a and b, field, base point) as well as pointers to the functions that
	should be used for point arithmetic and the underlying field GFMethod.
	Generated by either ECGroup_fromHex or ECGroup_fromName.

	GFMethod (from ecl-priv.h) - Represents a field underlying a set of
	elliptic curve domain parameters. Contains the irreducible that defines
	the field (either the prime or the binary polynomial) as well as
	pointers to the functions that should be used for field arithmetic.

	ARITHMETIC FUNCTIONS
	====================

	Higher-level algorithms (like ECDH and ECDSA) should call ECPoint_mul
	or ECPoints_mul (from ecl.h) to do point arithmetic. These functions
	will choose which underlying algorithms to use, based on the ECGroup
	structure.

	Point Multiplication
	--------------------

	ecl_mult.c provides the ECPoints_mul and ECPoint_mul wrappers.
	It also provides two implementations for the pts_mul operation -
	ec_pts_mul_basic (which computes kP, lQ, and then adds kP + lQ) and
	ec_pts_mul_simul_w2 (which does a simultaneous point multiplication
	using a table with window size 2*2).

	ec_naf.c provides an implementation of an algorithm to calculate a
	non-adjacent form of a scalar, minimizing the number of point
	additions that need to be done in a point multiplication.

	Point Arithmetic over Prime Fields
	----------------------------------

	ecp_aff.c provides point arithmetic using affine coordinates.

	ecp_jac.c provides point arithmetic using Jacobian projective
	coordinates and mixed Jacobian-affine coordinates. (Jacobian projective
	coordinates represent a point (x, y) as (X, Y, Z), where x=X/Z^2,
	y=Y/Z^3).

	ecp_jm.c provides point arithmetic using Modified Jacobian
	coordinates and mixed Modified_Jacobian-affine coordinates.
	(Modified Jacobian coordinates represent a point (x, y)
	as (X, Y, Z, a*Z^4), where x=X/Z^2, y=Y/Z^3, and a is
	the linear coefficient in the curve defining equation).

	ecp_192.c and ecp_224.c provide optimized field arithmetic.

	Field Arithmetic
	----------------

	ecl_gf.c provides constructors for field objects (GFMethod) with the
	functions GFMethod_cons*. It also provides wrappers around the basic
	field operations.

	Prime Field Arithmetic
	----------------------

	The mpi library provides the basic prime field arithmetic.

	ecp_mont.c provides wrappers around the Montgomery multiplication
	functions from the mpi library and adds encoding and decoding functions.
	It also provides the function to construct a GFMethod object using
	Montgomery multiplication.

	ecp_192.c and ecp_224.c provide optimized modular reduction for the
	fields defined by nistp192 and nistp224 primes.

	ecl_gf.c provides wrappers around the basic field operations.

	Field Encoding
	--------------

	By default, field elements are encoded in their basic form. It is
	possible to use an alternative encoding, however. For example, it is
	possible to Montgomery representation of prime field elements and
	take advantage of the fast modular multiplication that Montgomery
	representation provides. The process of converting from basic form to
	Montgomery representation is called field encoding, and the opposite
	process would be field decoding. All internal point operations assume
	that the operands are field encoded as appropriate. By rewiring the
	underlying field arithmetic to perform operations on these encoded
	values, the same overlying point arithmetic operations can be used
	regardless of field representation.

	ALGORITHM WIRING
	================

	The EC library allows point and field arithmetic algorithms to be
	substituted ("wired-in") on a fine-grained basis. This allows for
	generic algorithms and algorithms that are optimized for a particular
	curve, field, or architecture, to coexist and to be automatically
	selected at runtime.

	Wiring Mechanism
	----------------

	The ECGroup and GFMethod structure contain pointers to the point and
	field arithmetic functions, respectively, that are to be used in
	operations.

	The selection of algorithms to use is handled in the function
	ecgroup_fromNameAndHex in ecl.c.

	Default Wiring
	--------------

	Curves over prime fields by default use montgomery field arithmetic,
	point multiplication using 5-bit window non-adjacent-form with
	Modified Jacobian coordinates, and 2*2-bit simultaneous point
	multiplication using Jacobian coordinates.
	(Wiring in function ECGroup_consGFp_mont in ecl.c.)

	Curves over prime fields that have optimized modular reduction (i.e.,
	secp160r1, nistp192, and nistp224) do not use Montgomery field
	arithmetic. Instead, they use basic field arithmetic with their
	optimized reduction (as in ecp_192.c and ecp_224.c). They
	use the same point multiplication and simultaneous point multiplication
	algorithms as other curves over prime fields.