README for TinyECC Version 0.1

Author/Contact: aliu3@ncsu.edu

Introduction
------------

TinyECC is a software package providing Elliptic Curve Cryptography
(ECC) on TinyOS. By using this package, you can do all elliptic curve
operations, including point addition, point doubling and scalar point
multiplication. In addition to the basic elliptic curve operations, we
also implement ECDSA operations (signature generation and
verification) in this package. The natural number operations in
TinyECC are based on RSAREF2.0. We plan to include other ECC schemes
(e.g. ECDH) in this package in the future.


How to install
--------------

Steps 3~6 are required for the test program.

1) Install TinyOS 1.1.11 or a later version.

2) Extract TinyECC.zip to directory /opt/tinyos-1.x/apps/TinyECC.

3) Install JDK5.0 (http://java.sun.com/j2se/1.5.0/download.jsp) and
Bouncy Castle Provider for JCE (http://www.bouncycastle.org/). (This
step is necessary to use ECDSA in Java program.)

4) Download and install Sun's javax.comm package from
http://java.sun.com/products/javacomm/. You can use the following
steps (instructions for a cygwin shell), assuming you install JDK in
C:\Program Files\Java\jdk1.5.0:

  unzip javacomm20-win32.zip 
  cd commapi 
  cp win32com.dll "c:\Program Files\Java\jdk1.5.0\jre\bin" 
  chmod 755 "c:\Program Files\Java\jdk1.5.0\jre\bin\win32com.dll"
  cp comm.jar "c:\Program Files\Java\jdk1.5.0\jre\lib\ext" 
  cp javax.comm.properties "c:\Program Files\Java\jdk1.5.0\jre\lib"


5) There is a bug in Java Runtime Library (rt.jar). You have to fix
it if you want to use Koblitz curve in your Java programs. Fix it
using following steps, assuming you install JDK in
C:\Program Files\Java\jdk1.5.0:

  - Unzip C:\Program Files\Java\jdk1.5.0\src.zip.
  - Find EllipticCurve.java in
    C:\Program Files\Java\jdk1.5.0\src\java\security\spec\.
    In function checkValidity, modify "c.signum() != 1" to "c.signum() == -1".
  - Compile EllipticCurve.java to EllipticCurve.class.
  - Replace the old EllipticCurve.class in
    C:\Program Files\Java\jdk1.5.0\jre\lib\rt.jar with the newly
    compiled EllipticCurve.class.

6) Add the following lines into your makefile if your program is in
another directory. (Note that the maximum payload size in IEEE
802.15.4 is 102 bytes. The test program requires a packet with more
than 29 bytes (the TinyOS default maximum payload size) to include an
ECDSA signature.)

MSG_SIZE=102            //change maximum payload size to 102
PFLAGS=-I../TinyECC     //include TinyECC package


Interfaces provided
-------------------

1) NN.nc defines the interface NN, which provides big natural number
operations. Please read NN.nc for more details. NNM.nc implements this
interface.

2) ECC.nc defines the interface ECC, which provides the basic
elliptic curve operations and enhanced elliptic curve operations based
on sliding window method. Please read ECC.nc for more details. ECCM.nc
implements this interface.

3) ECDSA.nc defines the interface ECDSA, which provides the ECDSA
signature generation and verification. Please read ECDSA.nc for more
details. ECDSAM.nc implements this interface.

4) SHA1.nc defines the interface SHA1, which provides the SHA-1
functions. Please read SHA1.nc for more details. SHA1M.nc implements
this interface.

5) CurveParam.nc defines the interface CurveParam, which provides only
one function to get the parameters of elliptic curves. secp128*.nc,
secp160*.nc, secp192*.nc implement this interface to provide
parameters for SECG defined elliptic curves. You only need to change
ECCC.nc to modify the elliptic curve parameters.


Examples
--------

test_ECC.nc and test_ECCM.nc show how to use TinyECC.

Use the following steps to run examples. Assume you are using MICAz,
mib510 Programming and Serial Interface Board, which is connected to
COM4.

1) Program node, and then leave the node on the programming board.

        make micaz install mib510,/dev/ttyS3


2) Run SerialForwarder.

        java net.tinyos.sf.SerialForwarder -comm serial@COM4:57600 &


3) Run show_result.

        java show_result



Inline Assembly Code
--------------------

There are some inline assembly code in NNM.nc to speed up natural number
operations. These inline assembly code are written in AVR instruction
set. If you want to use TinyECC on other 8-bit platforms, you must comment
"#define INLINE_ASM" in NN.h.


Acknowledgement
---------------

NNM.nc is based on the natural number operations in RSAREF2.0.


TODO
----

1) Add other ECC schemes (e.g. ECDH) into TinyECC.

2) TinyECC has a bug related to Timer. If you use Timer in your
program, Timer.fired() will be called repeatedly. It will never stop even
you use "TIMER_ONE_SHOT" option. If you call Timer.stop() in
Timer.fired(), Timer.fired() can work correctly. We haven't figured out
the reason. We will try to solve this problem in the next version of TinyECC.