ECC-LIB (Version 2.1): A Software Library for Elliptic Curve Cryptography
    -------------------------------------------------------------------------


1. INTRODUCTION
---------------

Ecc-lib is a fully-equipped, portable, and modular library for Elliptic Curve (EC)
Cryptography that allows for the easy development of EC cryptographic protocols,
and which can be readily tailored to suit different requirements and user needs.
The library is implemented in ANSI C using the GNU Multiple Precision library
for high-precision floating point arithmetic.

The full source code is included, written entirely in standard,
portable ANSI C.


2. CONTENTS
-----------

The directory 'lib' contains the source files and the directory 'include'
the header files of the library. There is also an example program,
ecdsa.c, that implements the EC Digital Signature Algorithm (ECDSA)
taking input from a file (in 'ecdsa' directory), a file example.ps in 'doc'
directory that gives the detail of the ecdsa.c program.


3. COPYRIGHT
------------

There is a copyright on most of the implementations (see the corresponding files),
but permission is granted to use, copy, modify and distribute this software for
non-commercial purpose without fee, provided that the authors' names are still
included. All software in this package is  provided is distributed under the
General Public License (GPL). For details see file COPYING.


4. INSTALLATION
---------------

The library can be installed on all UNIX or LINUX workstations.
It is written in ANSI C and should compile using any ANSI C
compiler. The GNUMP library must have already been installed
in the system in which ecc-lib-2.1 will be installed.

In order to install ecc-lib-2.1, do the following:

1. Download the file ecc-lib-2.1.tar.gz

2. Uncompress and untar the file:

  tar xzf ecc-lib-2.1.tar.gz

3. The directory ECC-LIB-2.1 will be created.

4. To install the library, simple type "configure" and then "make" (within the ECC-LIB-2.1 directory).

After a while the library file libecc-lib.a will be created under the "lib/" directory.
In case the file libecc-lib.a does not appear and instead the file libecc-lib.la is created,
you should run, in addition, the following two commands in the "lib/" directory:
   ar crv libecc-lib.a *.o
   ranlib libecc-lib.a



5. HOW TO USE THE LIBRARY
-------------------------


Suppose you have created a file called test.c in the ECC-LIB-2.1 directory that uses some functions
of the library (see the file example.ps under the "doc/" directory). To create an executable, say test,
for that file just write

gcc -Iinclude -o test test.c lib/libecc-lib.a -lgmp



6. BRIEF DESCRIPTION OF THE LIBRARY
-----------------------------------

The basic constants of the library are:

1. bitlength: is defined in int_arithmetic.h and set the size of the
   underlying finite field F_p in bits.

2. num_of_digits: is defined in create_e_and_pi.c and defines the size
   of the floating point number (in bits) that are used in the construction
   of the Weber and Hilbert polynomials.

3. POLY_SIZE: is defined in poly_arithmetic.h and determines the maximum
   degree of the polynomials that are used.

4. n_loops: is defined in hilbert.c and determines the number of the loops
   in function F() in weber.c and in function Delta() in hilbert.c.

5. n_loops_baier: is defined in weber.h and determines the number
   of the loops in functions F_baier(), f0_baier(), f1_baier() and
   f2_baier() in weber.c.


The library consists of twelve source files and the corresponding twelve
header files. In particular:

In rmd160.c there are functions for the implementation of
the 160-bit hash function ripemd-160. In create_e_and_pi.c there are
functions that create the irrational numbers pi and e. Functions for floating point
arithmetic like cos, sin, ln, etc., exist in file float_point_arithmetic.c.
Some basic functions for modulo arithmetic, generation of a prime and factoring
of an integer are in the file int_arithmetic.c. In file complex_arithmetic.c
there are functions for complex arithmetic and in poly_arithmetic.c there
are functions for manipulating polynomials together with a function for
finding polynomial roots modulo a prime. The construction of Hilbert and Weber
polynomials is accomplished with the corresponding files hilbert.c and weber.c.
The basic elliptic curve operations are implemented in the file ec_operations.c
whereas file cm.c includes the necessary functions for the CM method. In file
cm_prime_order.c there are functions that are used for construction of prime
order elliptic curves. Finally, the file protocols.c includes all the functions
for the implementation of basic protocols (ECDSA, ECES, one-time pad encryption).

The use of every function is briefly explained in the header file that it is
included.


7. FURTHER REMARKS
------------------

We hope that you will find this package interesting or even stimulating
for further research. Any feedback regarding the software and especially
its use in another project would be greatly appreciated. Please send your
feedback to:

 ekonstantinou@aegean.gr  stamatiu@ceid.upatras.gr  zaro@ceid.upatras.gr



8. ACKNOWLEDGMENTS
------------------

We would like to thank Glenn McGrath (email: bug1@optushome.com.au) for
providing us with an autotool tailored version of our library.


We would also like to thank Bhanu Prakash & Pratik Poddar & Bernard Menezes 
(emails: {prakashb,pratik, bernard}@cse.iitb.ac.in) for the addition of two
functions in the file ec_operations.c (namely, point_mult_naf() and point_mult_window()).
These functions implement two different methods for point multiplication and their addition
in the ECC-LIB-2.1 library is the only difference between this version and the previous one
(ECC-LIB-2.0).