README.txt
----------

This is a "reference implementation" for a number of schemes
described in the ISO standard for public-key encryption (ISO/IEC 18033-2).
It was written by Anshuman Rawat and Victor Shoup.

The schemes here include 
   ACE-KEM, ECIES-KEM, PSEC-KEM, RSA-KEM, RSAES, DEM1, HC
The software is highly configurable:  using the C++ features of inheritance and
templates, one can synthesize a large number of different schemes  --- choose a
group, choose a hash function,  choose a MAC, choose a KDF,  choose a symmetric
cipher, choose a KEM, choose a DEM...each choice gives a different hybrid
cipher.  Mix and match! The software is also easily extensible  --- want to add
a new hash function, MAC, or block cipher? ...it's really easy!

This software is intended only for purposes of testing and evaluation. It is
not intended to be used for building programs that will be distributed publicly
--- indeed, there may be patents that affect some of the encryption schemes
implemented here.

This software does not come with much documentation...sorry! However, it was
written to be very easy to read...whenever there was a choice between
efficiency and clarity, preference was always given to clarity.

To compile this software, you will need the NTL library, which implements the
arithmetic on integers and polynomials, and you will need the "nettle" library,
which implements low-level cryptographic primitives. Before compiling, you will
need to edit the "makefile" in this directory just a little bit (read the
comments in the makefile...this is pretty easy). After this, just type "make"
at the command line. The end effect of this is the creation of the library file
"crypto.a".

There are also some scripts for generating test vectors (see below). To run
these scripts, you first have to edit the "compile" script (see below).

The NTL library may be obtained from 

   http://www.shoup.net/ntl

This software was tested using NTL with NTL_STD_CXX=on, although it
probably works (possibly with minor tweaking) otherwise.

The nettle librart can be obtained from  

   http://www.lysator.liu.se/~nisse/nettle

This software was tested using version 1.7 (there are lots of files on nettle's
download page...I have no idea what they are all for. Just find the file
"nettle-1.7.tar.gz".  There is apparently  now a version 1.8, but I haven't
tried that).


Good luck!

Here is a synopsis of the files in this directory:


# makefile for the library
makefile  # needs some editing 

# source files for the library
sc1.C
sc2.C
aes.C
crypto.C
dem1.C
group.C
hash.C
hc.C
hmac.C
kdf.C
ostring.C
rem1.C
rsa_kem.C
rsaes.C


# header files of the library
./include/crypto/:
ac.h
ace_kem.h
bc.h
crypto.h
dem.h
ecc.h
ecies_kem.h
group.h
hash.h
hc.h
kdf.h
kem.h
mac.h
ostring.h
psec_kem.h
rem.h
rsaes.h
sc.h


# input key files for the group
163.txt   # for ecgf2 groups
192.txt   # for ecmodp groups
grp.txt   # for modp groups

# file used to produce key for ecgf2 group
make-b163.C

# testing routines - not part of the library
test-ace.C
test-dem1.C
test-ecies.C
test-grp.C
test-hc.C
test-hmac.C
test-ostring.C
test-psec.C
test-rsaes.C
test-rsakem.C
test-sc1.C
test-sc2.C

# scripts for producing test vectors
compile   # file containing compiler & linker options...needs some editing

vector-ace
vector-ace1
vector-dem
vector-ecies
vector-ecies1
vector-hc
vector-psec
vector-psec1
vector-rsaes
vector-rsakem


# misc
pretty.c   # a C program to "prettify" the test vector output
README.txt # this file
 


