（3）Pairing Functions & Element Functions

以下内容源自PBC Library 的 英文manual（Chapter 3/4）。

本文摘要：

一，Pairing functions

• 1.1 Initializing pairings
• 1.2 Applying pairings
• 1.3 Other pairing functions

二，Element functions

• 2.1 Initializing elements
• 2.2 Assigning elements
• 2.3 Converting elements
• 2.4 Element arithmetic
• 2.5 Exponentiating elements
• 2.6 Comparing elements
• 2.7 Element I/O
• 2.8 Random elements
• 2.9 Element import/export

一.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 Chapter 7). 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_.

【译文】

应用程序应首先初始化一个配对对象。这导致PBC设置曲线，组和其他数学杂项。之后，可以对元素进行初始化和操作以进行加密操作。

param子目录中的PBC库分布中包含用于各种配对的参数，其中一些参数适合加密使用。== gen子目录中的某些程序可用于生成参数（请参见第7章）。另外，请参阅PBC网站以获取更多配对参数。==

配对涉及三个主要素数阶的群。 PBC库将它们称为G1，G2和GT，并称阶为r 。配对是一个双线性映射，它以两个元素作为输入，一个来自G1，一个来自G2，并输出GT元素。

G2的元素至少与G1一样长； G1保证是两者中较短的一个。有时G1和G2是同一组（即配对是对称的），因此它们的元素可以自由组合。在这种情况下，pairing_is_symmetric函数返回1。

双线性对存储在数据类型pairing_t中。对它们进行操作的功能以pairing_开头。

1.1. 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 Chapter 5).

int pairing_init_set_str(pairing_t pairing, const char *s)

Initialize pairing from parameters in a ASCIIZ string str Returns 0 on success, 1 on failure.

从一个ASCIIZ串的参数初始化配对，初始化成功则返回0，否则返回1。

int pairing_init_set_buf(pairing_t pairing, const char *s, size_t len)

Same, but read at most len bytes. If len is 0, it behaves as the previous function. Returns 0 on success, 1 on failure.

同样，但是最多读取len个字节，如果len是0，它就和上一个函数一样。

void pairing_init_pbc_param(struct pairing_s *pairing, pbc_param_t p)

Initialize a pairing with pairing parameters p.

用配对参数p来初始化一个配对。

void pairing_clear(pairing_t pairing)

Free the space occupied by pairing. Call whenever a pairing_t variable is no longer needed. Only call this after all elements associated with pairing have been cleared, as they need information stored in the pairing structure.

释放配对所占的空间。当一个pairing_t类型的变量没用的时候，就可以调用这个函数来释放该变量所占空间。因为需要存储在配对结构中的信息，所以只有所有与配对有关的元素都声明之后，才能调用这个函数。

1.2. 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_apply函数来应用双线性映射。 输入的顺序很重要。 保存输出的第一个必须来自组GT。 第二个必须来自G1，第三个必须来自G2，第四个必须是与它们相关的pairing_t变量。

在某些应用中，程序员可能知道会计算出具有相同G1输入的许多配对。 如果是这样，从长远来看，应该使用预处理以避免重复许多计算，从而节省了时间。 应该声明类型为pairing_pp_t的变量，并使用固定的G1元素进行初始化，然后将其用于计算配对：

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.

不要混合搭配来自不同配对的G1,G2和GT群。

void pairing_pp_init(pairing_pp_t p, element_t in1, pairing_t pairing)

Get ready to perform a pairing whose first input is in1,and store the results of time-saving precomputation in p.

准备执行第一个输入为in1的配对，存储这个节约时间的预计算结果到p.

void pairing_pp_clear(pairing_pp_t p)

Clear p. This should be called after p is no longer needed.

清除p。当不再用pairing_pp_t类型的变量p的时候，调用这个函数来回收。

void pairing_pp_apply(element_t out, element_t in2, pairing_pp_t p)

Compute a pairing using in2 and the preprocessed information stored in p and store the output in out. The inputs to the pairing are the element previously used to initialize p and the element in2.

使用in2和存储在p中的预处理信息计算一个配对，将输出存储在out中。

void element_pairing(element_t out, element_t in1, element_t in2)

Computes a pairing: out = e(in1, in2), where in1, in2, out must be in the groups G1, G2, GT.

计算一个配对࿱