== Pairing functions ==

An application should first initialize a pairing object. This causes PBC
to setup curves, groups and other mathematical miscellany. After that,
elements can be initialized and manipulated for cryptographic operations.

Parameters for various pairings are included with the PBC library distribution
in the `param` subdirectory, and some are suitable for cryptographic use. Some
programs in the `gen` subdirectory may be used to generate parameters (see
<<bundlechap>>). Also, see the PBC website for many more
pairing parameters.

Pairings involve three groups of prime order. The PBC library calls them G1,
G2, and GT, and calls the order r. The pairing is a bilinear map that takes two
elements as input, one from G1 and one from G2, and outputs an element of GT.

The elements of G2 are at least as long as G1; G1 is guaranteed to be the
shorter of the two. Sometimes G1 and G2 are the same group (i.e. the pairing
is symmetric) so their elements can be mixed freely. In this case the
+pairing_is_symmetric+ function returns 1.

Bilinear pairings are stored in the data type +pairing_t+. Functions that
operate on them start with +pairing_+.

=== Initializing pairings ===

To initialize a pairing from an ASCIIZ string:

  pairing_t pairing;
  pairing_init_set_str(pairing, s);  // Where s is a char *.

The string 's' holds _pairing parameters_ in a text format. The +param+
subdirectory contains several examples.

Alternatively, call:

  pairing_t pairing;
  pairing_init_pbc_param(pairing, param);

where 'param' is an initialized `pbc_param_t` (see <<paramchap>>).

include::gen/pairing_init.txt[]

=== Applying pairings ===

The function `pairing_apply` can be called to apply a bilinear map.  The order
of the inputs is important. The first, which holds the output, must be from the
group GT. The second must be from G1, the third from G2, and the fourth must be
the +pairing_t+ variable that relates them.

In some applications, the programmer may know that many pairings with the same
G1 input will be computed. If so, preprocessing should be used to avoid
repeating many calculations saving time in the long run.  A variable of type
+pairing_pp_t+ should be declared, initialized with the fixed G1 element, and
then used to compute pairings:

  pairing_pp_t pp;
  pairing_pp_init(pp, x, pairing); // x is some element of G1
  pairing_pp_apply(r1, y1, pp); // r1 = e(x, y1)
  pairing_pp_apply(r2, y2, pp); // r2 = e(x, y2)
  pairing_pp_clear(pp); // don't need pp anymore

Never mix and match G1, G2, and GT groups from different pairings.

include::gen/pairing_apply.txt[]

=== Other pairing functions ===

include::gen/pairing_op.txt[]