APIP LIBRARY 0.1 "development version" -------------------------------------- ------------------------------------------------------------------------------ 0. Contents ------------------------------------------------------------------------------ 1. About APIP 2. Legal 3. What is it? 4. Requirements 5. How to install 6. Where do things get installed? 7. What's in there? 8. Quick start ------------------------------------------------------------------------------ 1. About APIP ------------------------------------------------------------------------------ This is a development version of what will be the first public release of the APIP library / module for the PARI computer algebra system. APIP stands for (A)nother (P)airing (I)mplementation in (P)ari. Feel free to suggest alternatives. Constructive criticisms, suggestions and bug reports, are of course warmly welcomed. Send them to: milanj@lix.polytechnique.fr. ------------------------------------------------------------------------------ 2. Legal ------------------------------------------------------------------------------ The APIP library is Copyright (C) 2012 CNRS (French National Center for Scientific Research) - Ecole Polytechnique. The APIP library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. The APIP library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with the APIP library. If not, see . ------------------------------------------------------------------------------ 3. What is it? ------------------------------------------------------------------------------ The APIP library is a shared module for the PARI/GP computer algebra system implementing pairings over elliptic curves over large prime characteristic fields. Note that the special case of characteristic 2 and 3 are NOT implemented. APIP implements the Tate, Weil, ate and twisted ate pairings and optimized version of the ate and twisted ate pairing for some curve families. ------------------------------------------------------------------------------ 4. Requirements ------------------------------------------------------------------------------ This software is a dynamic library interfacing with the PARI computer algebra system which is downloadable from: http://pari.math.u-bordeaux.fr/ Needless to say, APIP will not build if PARI is not installed on your system. The APIP code matches the C99 standard so you'll obviously need a somewhat C99-compliant compiler. APIP has been developed and tested with the GCC C compiler version 4.2. Lastly, you will need the SCons tool version 2.0.0 or higher available at: http://www.scons.org to compile the APIP library. Note that you'll also need a distribution of Python version 2.4 (or higher depending on your version of SCons). Python is available at: http://www.python.org/download/ ------------------------------------------------------------------------------ 5. How to install? ------------------------------------------------------------------------------ APIP uses the Python-based SCons build tool in place of the more traditional autotools suite. Provided that you have the SCons tool installed and a not too old distribution of Python, building the APIP library should be as easy as with the autotools: 1) Edit the file BuildOptions.py in APIP's top directory. This file describes the parameters used during compilation and installation, so you should adapt it to your set-up or default values will be used. For a short overview of all of the relevant parameters, type "scons -h". 2) Compile the library by invoking SCons: prompt> scons 3) Finally, install the library: prompt> scons install Here is a brief list of the main SCons commands available: scons : build the APIP library and its programs scons install : install the APIP library scons -c : clean everything scons dist : create a tgz archive for distribution. (WARNING: due to current limitations of SCons, the generated tgz archive will expand in the current directory instead of creating a tifa-X.X.X directory and expanding the archive there...) ------------------------------------------------------------------------------ 6. Where do things get installed? ------------------------------------------------------------------------------ The installation process depends on the variables defined in BuildOptions.py. The APIP dynamic library libapip.so (or libapip.dylib) is installed in LIBDIR. For more information, type "scons -h". ------------------------------------------------------------------------------ 7. What's in there? ------------------------------------------------------------------------------ The source tree is organized as follow: apip/ src/ ................. Common functions char_2/ ........... Implementation of pairings in characteristic 2. WARNING: currently not useable. DO NOT USE IT. char_3/ ........... Implementation of pairings in characteristic 3. WARNING: currently not useable. DO NOT USE IT. char_p/ ........... Implementation of pairings in large characteristic. examples/ ............. Examples of GP scripts using most functions of the APIP module. ------------------------------------------------------------------------------ 8. Quick start ------------------------------------------------------------------------------ First, you'll have to compile and install the APIP shared module as previously explained. Edit the file "BuildOptions.py" to suit your needs and then, issue these commands in a shell: prompt> scons prompt> scons install APIP is quite flexible and provides lots of options. The easier place to start is to have a look at the numerous GP scripts given in the apip/examples/ directory. ------------------------------------------------------------------------------ 10. Troubleshooting ------------------------------------------------------------------------------ I can't even compile APIP! -------------------------- Check APIP's requirements at the beginning of this file. In particular, you should have Python installed on your system together with SCons v2.0.0 or higher and (of course) the PARI/GP computer algebra system. Can APIP run under OS X,Y,Z? ---------------------------- Maybe. But then again, maybe not. No particular effort was made to ensure compatibility with non-unix systems (such as Windows) but our bet is that APIP should be pretty easy to adapt to non-unix platforms provided that they are POSIX compliant and PARI/GP supports it. That said, we do not plan to support non-unix operating systems anyway, so in that case you're pretty much on your own. APIP gives wrong results! ------------------------ APIP was developed to study pairings in the context of cryptography where the points are expected to live in well defined groups. APIP is known to yield wrong results for pairings such as e(P,[n]P) where the two input points are taken from the same group. Fixing this will need quite some work. No effort is currently underway to implement it. Of course, feel free to contribute! Where are the pairings in characteristic 2 and 3? ------------------------------------------------- Pairings in characteristic 2 and 3 are currently not useable as APIP focuses on large prime characteristic. This may (or may not) be fixed in the future. Again, you are welcome to contribute.