Chapter 4. Element functions

Table of Contents

Initializing elements
Assigning elements
Converting elements
Element arithmetic
Exponentiating elements
Comparing elements
Element I/O
Random elements
Element import/export

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.

PBC_ASSERT(expr, msg)

Macro: if expr evaluates to 0, print msg and exit.

PBC_ASSERT_MATCH2(a, b)

Macro: if elements a and b are from different fields then exit.

PBC_ASSERT_MATCH3(a, b, c)

Macro: if elements a, b and c are from different fields then exit.

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.

void element_init_G1(element_t e, pairing_t pairing)

void element_init_G2(element_t e, pairing_t pairing)

void element_init_GT(element_t e, pairing_t pairing)

Initialize e to be an element of the group G1, G2 or GT of pairing.

void element_init_Zr(element_t e, pairing_t pairing)

Initialize e to be an element of the ring Z_r of pairing. r is the order of the groups G1, G2 and GT that are involved in the pairing.

void element_init_same_as(element_t e, element_t e2)

Initialize e to be an element of the algebraic structure that e2 lies in.

void element_clear(element_t e)

Free the space occupied by e. Call this when the variable e is no longer needed.