Disclaimer
THE AUTHORS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
EVENT SHALL THE AUTHORS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE. 

Author: Feng Zhu
e-mail: zhufeng@ccs.neu.edu

Date of ECClib.prc: January 12, 2003
Version: 0.1

If you have any suggestions please write to the author.  

Description:

ECClib is a Palm OS Library that implements the operations over elliptic curves.

To use this Palm Library, you need to:

1.  Download the ECClib.prc
2.  Download the ECClib.h
3.  Download the ecc.h
4.  Only include the ECClib.h in your file.

===============================================================

Elliptic Curve parameters

(1)   The random curve over GF(2^191);
   
The field F(2^191) is generated by the irreducible polynomial 
       80000000      00000000      00000000      00000000      00000000 
       00000201 
    or say,  X^191 + X^9 + 1;

The elliptic curve is E : y^2 + xy = x^3 + ax^2 + b over F(2^191), where 
a =    2866537B      67675263      6A68F565      54E12640      276B649E 
       F7526267 
b =    2E45EF57      1F00786F      67B0081B      9495A3D9      5462F5DE 
       0AA185EC 
  
Generating point is (without point compression) 
G =          04      36B3DAF8      A23206F9      C4F299D7      B21A9C36 
       9137F2C8      4AE1AA0D      765BE734      33B3F95E      332932E7 
       0EA245CA      2418EA0E      F98018FB 
  
The order of G is 
r =    40000000      00000000      00000000      04a20e90      c39067c8 
       93bbb9a5 
  
The cofactor is 
k =    2 

Ref: SAMPLE TEST VECTORS FOR P1363 

(2) The Koblitz curve over GF(2^191);
The field F(2^163) is generated by the irreducible polynomial 
f (x) = x^163+x^7+x^6+x^3 +1

The curve E: y2+xy = x3+ax2+b over F(2^163) is defined by:
a = 00 00000000 00000000 00000000 00000000 00000001
b = 00 00000000 00000000 00000000 00000000 00000001

The base point G is:
G = 0402FE 13C0537B BC11ACAA 07D793DE 4E6D5E5C 94EEE802 89070FB0
    5D38FF58 321F2E80 0536D538 CCDAA3D9

The order n of G and the cofactor are:
n = 04 00000000 00000000 00020108 A2E0CC0D 99F8A5EF
h = 02

Ref: SEC 2: Recommended Elliptic Curve Domain Parameters, Certicom Research, 
     September 20, 2000, Version 1.0

===============================================================
How to use the ECClib:

1. First you need to open the Library. 
The sample code is as follows:

	err = SysLibFind("ECCLib", &ECCLibRefNum);
	if (err) err = SysLibLoad('libr', 'FZSL', &ECCLibRefNum);
	ErrFatalDisplayIf(err, "Cannot load ECC Library");
	err = ECCOpen(ECCLibRefNum);

Where ECCLibRefNum is a static UInt16, used to store where is 
the ECCLibrary.

We sugest that you put this code in your StartApplication() function, or
in the function you use to initialize your application.

2.  How to use ECClib?

Data Structure
--------------
typedef unsigned long  word;

#define BitLengthOfPoly 192
#define wordLengthOfPoly  BitLengthOfPoly/(sizeof(word)*8)

typedef struct {
	word Poly[ wordLengthOfPoly ];
} gf2nPoint;

typedef struct {
	gf2nPoint ModPoly;
	word SquTab[16];
} GFBASE;

typedef struct {
	gf2nPoint X, Y;
	int IsInfinity;
} eccPoint;

typedef struct {
	gf2nPoint a, b; /* y^2 +xy = x^3 +ax^2 + b. */
	eccPoint G; /* Generating Point  */
	GFBASE gfBase;
} ECCBASE;

 For example
   gf2nPoint X;
   X.Poly[0] = 0x80000000; X.Poly[1] = 0; X.Poly[2] = 0; X.Poly[3] = 0;  X.Poly[4] = 0; X.Poly[5] = 0x00000201; 
   Then X stand for X^191 + X^9 + 1;

Initialization Functions
------------------------
ECCErr ECCLIBeccInit(ECCLibRefNum, &eccBase);


Assignment Function
-------------------
ECCErr ECCLIBeccCopy(Int16 refNum, eccPoint *R, const eccPoint *P)
sets R = P

Arithmetic Functions
--------------------

ECCErr ECCLIBeccAdd(Int16 refNum, eccPoint *R, const eccPoint *P, const eccPoint *Q, ECCBASE *eccBase)
sets R = P + Q  

ECCErr ECCLIBeccDouble(Int16 refNum, eccPoint *R, const eccPoint *P, ECCBASE *eccBase)
set R = 2P

ECCErr ECCLIBeccMul(Int16 refNum, eccPoint *R, const eccPoint *P, const word *s, ECCBASE *eccBase)
set R= sP
where s is an array of 6 words
For examples
  If,   word s[ wordLengthOfPoly ];
	s[0] = 0x00000001;
	s[1] = 0xdda332f9;
	s[2] = 0xd2aec168;
	s[3] = 0x249b5696;
	s[4] = 0xee39d0ed; 
        s[5] = 0x4d03760f;
  Then  s    =   00000001 dda332f9 d2aec168 249b5696 ee39d0ed 4d03760f 
  s should be less than the order of the group G.
  
3.  How to Close the Library?

You can close the library when you finished.  This is accomplished via:
	
	error = ECCClose(ECCLibRefNum, &numapps);  // check for erros in the Close() routine
	if (numapps == 0) SysLibRemove(ECCLibRefNum);

We suggest you include this code in the StopApplication() function
or your function used to handle the case of closing the application.