1 files changed, 69 insertions, 0 deletions
diff --git a/moon-abe/pbc-0.5.14/doc/pairingfns.txt b/moon-abe/pbc-0.5.14/doc/pairingfns.txt
new file mode 100644
index 00000000..4ea4bf13
--- /dev/null
+++ b/moon-abe/pbc-0.5.14/doc/pairingfns.txt
@@ -0,0 +1,69 @@
+== 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[]