PBC LIBRARY 0.2 MANUAL
======================

Quick Start
-----------

After compilation succeeds, try:

./testpairing < a.param

./benchmark < c159.param

./testibe < e.param

See below for more details on the test programs.

Test Programs
-------------

testmnt
    This produces parameters for a curve suitable for computing pairings.
The output can be fed to some of the other test programs.

testsig
    Reads curve parameters on standard input and performs computations
that would be required in an implementation of the Boneh-Lynn-Shacham
short signature scheme.
    
testibe
    Reads curve parameters on standard input and performs computations
that would be required in an implementation of the Boneh-Franklin
identity-based encryption scheme.

testbb, testbls
    These test the Boneh-Boyen and Boneh-Lynn-Shacham signature functions.
I intend to split off code dealing with signatures into a separate library,
as I feel this library should be strictly about the pairing and not
applications.
    Reads curve parameters on standard input.

testbbs
    Gives rough timing results one would expect from an implementation of
the BBS group signature scheme.
    Reads curve parameters on standard input.

benchmark
    Benchmarks the pairings. Reads pairing parameters on standard input.

Tutorial
--------
Programs using the PBC library should include the file pbc.h:

    #include "pbc.h"

and linked with the libpbc library, e.g.

    gcc program.c -L. -lpbc

The file pbc.h includes gmp.h thus all GMP functions are available.

To use a pairing, first declare it:

    pairing_t pairing;

Then initialize it:

    pairing_init_inp_str(pairing, stdin);

In this case, the pairing parameters are fed to the program on standard
input (e.g. "./program < a.param"). Now pairing->G1, pairing->G2,
pairing->GT and bilinear_map() can be used as follows.
Declare some group elements:

    element_t x, y, z;

And initialize them

    element_init(x, pairing->G1);
    element_init(y, pairing->G2);
    element_init(z, pairing->GT);

Pick random elements of G1, G2:

    element_random(x);
    element_random(y);

Compute a pairing:

    bilinear_map(z, x, y, pairing);

Now z = e(x, y).

Pairing Types
-------------
The PBC library implements the pairing using different types of curves.
Which curve to use depends on the application. To make it easy to refer to
them, I have labelled them with letters. See below for the details.

The library provides pairing parameters useful in typical pairing-based
cryptosystems. If you're not interested in what the details are, always
use "a.param" when a fast pairing is desired, and "c159.param" when short
group elements are needed.

Type A
------
We use the curve y^2 = x^3 + x over the field F_q for some prime q.
It turns out #E(F_q) = q + 1 and #E(F_q^2) = (q+1)^2.
Thus the embedding degree k is 2.

We set things up so that q + 1 = r * h, for a particular r. For speed,
we pick r to be a Solinas prime, that is, r has the form 2^a +- 2^b +- 1
for some integers 0 < b < a.

We also choose q = -1 mod 12 so we can implement F_q^2 as F_q[i]
(where i = sqrt(-1)). Also, since q = -1 mod 3, cube roots in F_q
are easy to compute. This latter feature may be removed because I have
not found a use for it yet (in which case only q = -1 mod 4 is guaranteed).

Pairings on type A curves are the fast and ought to be used where the
main concern is efficiency. Typically, r should be about 160 bits long
and q about 512 bits. In this case, elements of groups G1 and G2 take
512 bits to represent.

Additionally, the pairing is symmetric, that is G1 and G2 are in fact
the same group.

a_param struct fields:
exp2, exp1, sign1, sign0, r:
    r = 2^exp2 + sign1 * 2^exp1 + sign0 * 1 (Solinas prime)
q, h:
    r * h = q + 1
    q is a prime, h is a multiple of 12 (thus q = -1 mod 12)

Type B
------
This type is reserved for the curve y^2 = x^3 + 1 over F_q with
q = -1 mod 12. It has yet to be implemented as I have not seen a compelling
reason to use it.

There are advantages unique to this curve however. Since cube roots in F_q
are fast and guaranteed to exist, for any given value of y, it is easy to
solve for x. Also, with the coefficient of x is zero in the curve equation,
simplifying some equations (e.g. point doubling).

There is also at least one drawback when compared with the similar type A
pairing. If symmetry of the pairing is insisted upon, some optimizations are
not possible. If ever implemented, perhaps I will divide this case into two
subtypes, one symmetric, and the other asymmetric but slightly faster.

Type C
------
These are ordinary curves of with embedding degree 6, whose orders are prime
or a prime multiplied by a small constant. These are constructed using the
method due to MNT.

Ideally, the embedding degree would be a slightly higher even number, say 8,
10 or 12, but unfortunately it is not known how to construct these.

A type C curve is defined over some field F_q and has order h * r where
r is a prime and h is a small constant. Over the field F_q^6 its order is
a multiple of r^2.

Typically the order of the curve E is around 170 bits, as is F_q, the base
field, thus q^k is around the 1024-bit mark which is commonly considered
good enough.

Using type C pairings allows elements of group G1 to be quite short, typically
170-bits. Because of a certain trick, elements of group G2 need only be 3 times
longer, that is, about 510 bits rather than 6 times long. They are not quite
as short as type F pairings, but much faster.

c_param struct fields:
q   F_q is the base field
n   # of points in E(F_q)
r   large prime dividing n
h   n = h * r
a   E is given by y^2 = x^3 + ax + b
b
nk  # of points in E(F_q^k)
hk  nk = hk * r * r

Type D
------
This type is reserved for supersingular curves with embedding degree 6.
Pairings are fast as optimizations specific to fields of characteristic 3
may be used. The embedding degree of 6 also means the representations of
elements of G1 are short.

On the other hand, the low characteristic also makes these curves more
susceptible to Coppersmith's attack, so slightly larger fields are needed
for security.

Type E
------
The CM (Complex Multiplication) method of constructing elliptic curves
starts with the Diophantine equation

    DV^2 = 4q - t^2

If t = 2 and q = D r^2 h^2 + 1 for some prime r (which we choose to
be a Solinas prime) and some integer h, we find that this equation is easily
solved with V = 2rh.

Thus it is easy to find a curve (over the field F_q) with order q - 1.
Note r^2 divides q - 1, thus we have an embedding degree of 1.

Hence all computations necessary for the pairing can be done in F_q alone.
There is never any need to extend F_q.

As q is typically 1024-bits, group elements take a lot of space to represent.
Moreover, many optimizations do not apply to this type, resulting in a slower
pairing.

This pairing is kept as a reserve, in case some day it is discovered
that discrete log in field extensions is easier to solve than previously
thought.

Type F
------
Using carefully crafted polynomials, k = 12 pairings can be constructed.
Only 160 bits are needed to represent elements of one group, and 320 bits
for the other.

They should be used when the top priority is to minimize bandwidth (e.g.
short signatures). The pairing is slower than the other types.

Also, k = 12 allows higher security short signatures. (k = 6 curves cannot
be used to scale security from 160-bits to say 256-bits because finite
field attacks are subexponential.)

------------------------------------------------------------------------------
Ben Lynn <blynn@cs.stanford.edu>
