diff options
Diffstat (limited to 'moon-abe/pbc-0.5.14/doc/elementfns.txt')
-rw-r--r-- | moon-abe/pbc-0.5.14/doc/elementfns.txt | 111 |
1 files changed, 0 insertions, 111 deletions
diff --git a/moon-abe/pbc-0.5.14/doc/elementfns.txt b/moon-abe/pbc-0.5.14/doc/elementfns.txt deleted file mode 100644 index cadf78b0..00000000 --- a/moon-abe/pbc-0.5.14/doc/elementfns.txt +++ /dev/null @@ -1,111 +0,0 @@ -== Element functions == - -Elements of groups, rings and fields are stored in the +element_t+ data type. -Variables of this type must be initialized before use, and should be cleared -after they are no longer needed. - -The +element_+ functions must be used with caution. Just as division by zero -does not make sense for integers, some operations may not make sense for -particular elements. For example, in a ring, one cannot in general invert -elements. - -Another caveat is that many of these functions assume their arguments come from -the same ring, group or field. No implicit type casting is performed. - -For debug builds, turn on run-time checks by defining `PBC_DEBUG` before -including `pbc.h`: - - #define PBC_DEBUG - #include <pbc.h> - -Also, when `PBC_DEBUG` is defined, the following macros are active. -Normally they are replaced with empty statements. - -include::gen/debug.txt[] - -=== Initializing elements === - -When an element is initialized it is associated with an algebraic structure, -such as a particular finite field or elliptic curve group. - -We use G1 and G2 to denote the input groups to the pairing, and GT for the -output group. All have order r, and Zr means the ring of integers modulo r. -G1 is the smaller group (the group of points over the base field). With -symmetric pairings, G1 = G2. - -include::gen/einit.txt[] - -=== Assigning elements === - -These functions assign values to elements. When integers are assigned, -they are mapped to algebraic structures canonically if it makes sense -(e.g. rings and fields). - -include::gen/eassign.txt[] - -=== Converting elements === - -include::gen/econvert.txt[] - -=== Element arithmetic === - -Unless otherwise stated, all +element_t+ arguments to these functions must have -been initialized to be from the same algebraic structure. When one of these -functions expects its arguments to be from particular algebraic structures, -this is reflected in the name of the function. - -The addition and multiplication functions perform addition and multiplication -operations in rings and fields. For groups of points on an ellitpic curve, such -as the G1 and G2 groups associated with pairings, both addition and -multiplication represent the group operation (and similarly both 0 and 1 -represent the identity element). It is recommended that programs choose and -one convention and stick with it to avoid confusion. - -In contrast, the GT group is currently -implemented as a subgroup of a finite field, so only multiplicative operations -should be used for GT. - -include::gen/earith.txt[] - -=== Exponentiating elements === - -Exponentiation and multiexponentiation functions. If it is known in advance -that a particular element will be exponentiated several times in the future, -time can be saved in the long run by first calling the preprocessing function: - - element_pp_t g_pp; - element_pp_init(g_pp, g); - element_pp_pow(h, pow1, g_pp); // h = g^pow1 - element_pp_pow(h, pow2, g_pp); // h = g^pow2 - element_pp_pow(h, pow3, g_pp); // h = g^pow3 - element_pp_clear(g_pp); - -include::gen/epow.txt[] - -=== Comparing elements === - -These functions compare elements from the same algebraic structure. - -include::gen/ecmp.txt[] - -=== Element I/O === - -Functions for producing human-readable outputs for elements. -Converting elements to and from bytes are discussed later. - -include::gen/eio.txt[] - -=== Random elements === - -Only works for finite algebraic structures. Effect on polynomial rings, fields -of characteristic zero, etc. undefined. - -See <<randomref>> for how PBC gets random bits. - -include::gen/erandom.txt[] - -=== Element import/export === - -Functions for serializing and deserializing elements. - -include::gen/etrade.txt[] |