README for Stanford IBE library v0.7.2Ben Lynn <blynn@cs.stanford.edu>INTRODUCTIONThe Stanford IBE library is a C implementation of the Boneh-Franklinidentity-based encryption scheme. (See Boneh and Franklin, "Identity-BasedEncryption from the Weil Pairing", CRYPTO 2001.)There are a few modifications and additions. The Boneh-Franklin scheme isused as a Key Encapsulation Mechanism, and off-the-shelf ciphers and HMACsare used for the actual encryption. (See Lynn, "Authenticated Identity-BasedEncryption", available on eprint.)Identity-based signatures have also been implemented. The Boneh-Lynn-Shachamscheme is used (see Boneh, Lynn and Shacham, "Short Signatures from theWeil Pairing", ASIACRYPT 2001.) Certificates are employed to make the signaturesidentity based. However, using a trick that we call "signature aggregation" (thatwill be described in a forthcoming paper), there is not much overhead comparedto other ID-based signature schemes.The library uses the GMP library (http://www.swox.com/gmp/) for low-levelarithmetic and the OpenSSL library (http://www.openssl.org/) for variouscryptographic primitives.It is still under heavy development so the API could change dramaticallyin future versions. (This already happened several times recently.)DESCRIPTIONThe lowest layer is fp2.c, which uses GMP to perform arithmetic in F_p^2.It defines the fp2_t data type, which represents elements of F_p^2.The next layer is curve.c, which performs the elliptic curve arithmetic.It defines the point_t data type, which represents points on the curve.It only supports specific curves so that certain optimizations can beapplied. (For example, it assumes p is a Solinas prime that is 11 mod 12and that a particular curve is being used.)Furthermore, some functions assume that the points are on E/F_p, notE/F_p^2.On top of this lies ibe_lib.c, which does basic IBE operations.It defines the params_t data type, which represents IBE system parameters.The headers are in ibe.h. Originally these were routines that performed thefour IBE operations described in the IBE paper and Authenticated IBE paper(Setup, Extract, Encrypt, Decrypt and authenticated versions), but now the BFIBE system is used as Key Encapsulation Mechanism instead, and off-the-shelfencryption and HMAC algorithms (from OpenSSL) are used in place of theconstruction of Fujisaki and Okamoto.The file ibe.h is the most important one for application programmers. In fact,one could easily build IBE applications using only the functions declared in thisfile, provided that one already has access to a library that can do encryptionand decryption (such as OpenSSL, or the file crypto.c that is described next).The code in crypto.c essentially consists of wrappers around OpenSSL functions.This is so that another crypto library can be substituted in later, if needed.Its role is to provide encryption, decryption and random number generationroutines.Next, format.c uses ibe_lib.c and crypto.c to show how the library can beused in applications. I called it "format" because it contained code forsaving and loading various file formats, and it is here these formats aredefined.The gen and ibe programs are applications that use the above. They arecommand-line tools that allow people to run IBE systems.The file byte_string.c defines a data type called byte_string_t that holds astring of bytes, and also contains various utility functions for it.They were needed because ASCIIZ strings were not sufficient.mm.* and benchmark.* are for debugging and benchmarking. By default,the "void" versions will be used, and any functions starting with mm_ or bm_can be ignored.There are also a bunch of test programs, but the most important one istorture.c, as the library cannot be trusted if "torture -m2" does notrun successfully (and without memory leaks).Run "torture -h" to see how to use it.The library is thread-safe except for IBE_init() and IBE_clear().The data types were modeled on the GMP data types. For example,to use byte_string's:Declare with:    byte_string_t foo;Initialize with:    byte_string_init(foo, n);        where n = length of byte stringNow you can assign to foo->data[0] to foo->data[n-1], which holdunsigned chars, and also foo->length = n.Free with:    byte_string_clear(foo);INSTALLATIONLinux:1.Install the GMP and OpenSSL libraries.2.Edit the Makefile and change the directories as needed.3.Run make.Make ibe_test for a simple test program (ibe_test).Cross-compiling for Windows:I have only done this with the mingw32 compiler included with the Testingdistribution of Debian GNU/Linux (http://www.debian.org/).1. Cross-compile GMP and OpenSSL.2. Run "make WIN32=1"USAGEFor users:See ibe_help.txt.For programmers:Look at ibe_test.c for a specific example.1) Include ibe.h and format.h in the program. (ibe_test.c doesn't need to  include format.h because it doesn't load/save files.)2) Call IBE_init() to initialize the library.3) Now system parameters are needed. Declare a params_t type, e.g.    params_t params;  You can either generate new ones via IBE_setup(), or load them from a file,  via FMT_load_params(), e.g.  FMT_load_params(params, "params.txt");4) Then call the various FMT_* or IBE_* functions to do what you want.  FMT_* is a wrapper around the IBE_* functions and deals with files,  and IBE_* are the lower level functions and deals with memory buffers.5) Call params_clear(params) to free the system parameters.  Call IBE_clear() to free the memory used by the library.I wrote a command-line program, called "ibe.c", which does the commonly-usedoperations you'd expect. See ibe_help.txt on how to use it.See gen.c on how to generate system parameters and save them, and also on howto split the master secret and then save the pieces. (Each piece is then copiedto a server, and the PKG is run on that server using that piece.)See combine.c on how to combine private key shares together to form a privatekey.  (Right now it's quite insecure because each piece is encrypted with thesame password, so that's why the generate_password() function looks useless.This'll be fixed eventually.)See encrypt.c on how to encrypt a given message with a given ID,and decrypt.c on how to decrypt a given message with a given private key.REFERENCES1. http://www.openssl.org/    OpenSSL library.2. http://www.swox.com/gmp/    GMP library.3. http://crypto.stanford.edu/ibe/    Stanford IBE project page. Contains online version of Boneh andFranklin's paper. Also a link to my homepage where more relevant papers maybe found.