以下內容源自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.
計算一個配對：out=e(in1,in2)，in1屬於G1，in2屬於G2，out屬於GT。
void element_prod_pairing(element_t out, element_t in1[], element_t in2[], int n)
Computes the product of pairings, that is out = e(in1[0], in2[0]) … e(in1[n-1], in2[n-1]). The arrays in1, in2 must have at least n elements belonging to the groups G1, G2 respectively, and out must belong to the group GT.
計算配對的乘積，即out = e（in1 [0]，in2 [0]）…e（in1 [n-1]，in2 [n-1]）。 數組in1，in2必須至少具有分別屬於組G1，G2的n個元素，而數組out必須屬於組GT。
1.3. Other pairing functions
int pairing_is_symmetric(pairing_t pairing)
Returns true if G1 and G2 are the same group.
判斷是否對稱。
int pairing_length_in_bytes_G1(pairing_t pairing)
Returns the length in bytes needed to represent an element of G1.
返回G1元素所需的字節長度。
int pairing_length_in_bytes_x_only_G1(pairing_t pairing)
Returns the length in bytes needed to represent the x-coordinate of an element of G1.
返回G1元素的x座標所需要的字節長度。
int pairing_length_in_bytes_compressed_G1(pairing_t pairing)
Returns the length in bytes needed to represent a compressed form of an element of G1. There is some overhead in decompressing.
返回G1元素壓縮格式所需的字節長度 ，解壓縮會有一些開銷。
int pairing_length_in_bytes_G2(pairing_t pairing)
Returns the length in bytes needed to represent an element of G2.
返回G2元素所需的字節長度。
int pairing_length_in_bytes_compressed_G2(pairing_t pairing)
Returns the length in bytes needed to represent a compressed form of an element of G2. There is some overhead in decompressing.
返回G2元素壓縮格式所需的字節長度 ，解壓縮會有一些開銷。
int pairing_length_in_bytes_x_only_G2(pairing_t pairing)
Returns the length in bytes needed to represent the x-coordinate of an element of G2.
返回G2元素的x座標所需要的字節長度。
int pairing_length_in_bytes_GT(pairing_t pairing)
Returns the length in bytes needed to represent an element of GT.
返回GT元素所需的字節長度。
int pairing_length_in_bytes_Zr(pairing_t pairing)
Returns the length in bytes needed to represent an element of Zr.
返回Zr元素所需的字節長度。
二.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.
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.
2.1. 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)
初始化e爲G1羣上的元素。
void element_init_G2(element_t e, pairing_t pairing)
初始化e爲G2羣上的元素。
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.
初始化e爲GT羣上的元素。
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.
初始化e爲配對上的環Zr上的一個元素。r是配對中的羣G1，G2，GT的階。
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.
初始化e爲e2所在代數結構的一個元素。
void element_clear(element_t e)
Free the space occupied by e. Call this when the variable e is no longer needed.
當變量e不再使用的時候調用這個函數來釋放e佔用的空間。
2.2. 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).
void element_set0(element_t e)
Set e to zero.
設定e的值爲0。
void element_set1(element_t e)
Set e to one.
設定e的值爲1。
void element_set_si(element_t e, signed long int i)
Set e to i.
設定e的值爲i。
void element_set_mpz(element_t e, mpz_t z)
Set e to z.
設置e的值爲z的值。
void element_set(element_t e, element_t a)
Set e to a.
設置e的值爲元素a的值。
2.3. Converting elements
void element_to_mpz(mpz_t z, element_t e)
Converts e to a GMP integer z if such an operation makes sense.
在有意義的前提下，將z轉化爲一個GMP整數。
void element_from_hash(element_t e, void *data, int len)
Generate an element e deterministically from the len bytes stored in the buffer data.
根據存儲在緩衝區的len字節長度的數據，確定性地生成一個元素e。
2.4. 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.
【譯文】
除非另有說明，否則這些函數的所有element_t參數都必須已初始化爲來自相同的代數結構。 當某個函數的參數是特定的代數結構時，將以函數的名稱反映出來。
加法和乘法功能在環和域中執行加法和乘法運算。 對於橢圓曲線上的點組，例如與配對關聯的羣G1和G2，加法和乘法均表示羣操作（類似地，0和1均表示標識元素）。 建議程序選擇一個約定，並遵守約定以避免混淆。
相比之下，羣GT當前被實現爲有限域的子羣，因此GT僅使用乘法運算。
void element_add(element_t n, element_t a, element_t b)
Set n to a + b.
void element_sub(element_t n, element_t a, element_t b)
Set n to a - b.
void element_mul(element_t n, element_t a, element_t b)
Set n = a*b.
void element_mul_mpz(element_t n, element_t a, mpz_t z)
void element_mul_si(element_t n, element_t a, signed long int z)
Set n = a z, that is a + a + … + a where there are z a’s.
設置n = a*z，即a + a + … + a，其中有z 個a。
void element_mul_zn(element_t c, element_t a, element_t z)
z must be an element of a integer mod ring (i.e.Zn for some n). Set c = a*z, that is a + a + … + a where there are z a’s.
z必須是一個整數模環的元素（即對於某個n的環Zn）。設置 c = a*z，即a + a + … + a，z個a相加。
void element_div(element_t n, element_t a, element_t b)
Set n = a / b.
void element_double(element_t n, element_t a)
Set n = a + a.
void element_halve(element_t n, element_t a)
Set n = a/2.
void element_square(element_t n, element_t a)
Set n = a2.
設置n爲a的平方。
void element_neg(element_t n, element_t a)
Set n = -a.
void element_invert(element_t n, element_t a)
Set n to the inverse of a.
設置n爲a的倒數。
2.5. 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);
void element_pow_mpz(element_t x, element_t a, mpz_t n)
Set x = an, that is a times a times … times a where there are n a’s.
設置x = an。
void element_pow_zn(element_t x, element_t a, element_t n)
Set x=an,where n is an element of a ring ZN for some N (typically the order of the algebraic structure x lies in).
令x=an,n是某個整數N的環ZN上的元素（N通常是x所在代數結構的階）。
void element_pow2_mpz(element_t x, element_t a1, mpz_t n1, element_t a2, mpz_t n2)
Sets x = a1n1 a2 n2, and is generally faster than performing two separate exponentiations.
令x=a1n1 a2n2,通常比分別執行求冪運算要快。
void element_pow2_zn(element_t x, element_t a1, element_t n1, element_t a2, element_t n2)
Also sets x = a1n1 a2n2, but n1, n2 must be elements of a ring Zn for some integer n.
void element_pow3_mpz(element_t x, element_t a1, mpz_t n1, element_t a2, mpz_t n2, element_t a3, mpz_t n3)
Sets x = a1n1 a2n2 a3n3, generally faster than performing three separate exponentiations.
void element_pow3_zn(element_t x, element_t a1, element_t n1, element_t a2, element_t n2, element_t a3, element_t n3)
Also sets x = a1n1 a2n2 a3n3, but n1, n2, n3 must be elements of a ring Zn for some integer n.
void element_pp_init(element_pp_t p, element_t in)
Prepare to exponentiate an element in, and store preprocessing information in p.
void element_pp_clear(element_pp_t p)
Clear p. Should be called after p is no longer needed.
void element_pp_pow(element_t out, mpz_t power, element_pp_t p)
Raise in to power and store the result in out, where in is a previously
preprocessed element, that is, the second argument passed to a previouselement_pp_initcall.
void element_pp_pow_zn(element_t out, element_t power, element_pp_t p)
Same except power is an element ofZn for some integer n.
void element_dlog_brute_force(element_t x, element_t g, element_t h)
Computes x such that gx = h by brute force, where x lies in a field where element_set_mpz() makes sense.
void element_dlog_pollard_rho(element_t x, element_t g, element_t h)
Computes x such that gx = h using Pollard rho method, where x lies in a field where element_set_mpz() makes sense.
2.6. Comparing elements
These functions compare elements from the same algebraic structure.
int element_is1(element_t n)
Returns true if n is 1.
int element_is0(element_t n)
Returns true if n is 0.
int element_cmp(element_t a, element_t b)
Returns 0 if a and b are the same, nonzero otherwise.
int element_is_sqr(element_t a)
Returns nonzero if a is a perfect square (quadratic residue), zero otherwise.
int element_sgn(element_t a)
int element_sign(element_t a)
If a is zero, returns 0. For nozero a the behaviour depends on the algebraic structure, but has the property that element_sgn(a) = -element_sgn(-a) and element_sgn(a) = 0 implies a = 0 with overwhelming probability.
2.7. Element I/O
Functions for producing human-readable outputs for elements. Converting elements to and from bytes are discussed later.
size_telement_out_str(FILE * stream, int base, element_t e)
Output e on stream in base base. The base must be between 2 and 36.
int element_printf(const char *format, …)
int element_fprintf(FILE * stream, const char *format, …)
int element_snprintf(char *buf, size_t size, const char *fmt, …)
int element_vsnprintf(char *buf, size_t size, const char *fmt, va_list ap)
Same as printf family except also has the B conversion specifier for types ofelement_t, and Y, Z conversion specifiers for mpz_t. For example if e is of type element_t then
element_printf("%B\n", e); will print the value of e in a human-readable form on standard output.
int element_snprint(char *s, size_t n, element_t e)
Convert an element to a human-friendly string. Behaves assnprintfbut only on one element at a time.
int element_set_str(element_t e, const char *s, int base)
Set the element e from s, a null-terminated C string in base base. Whitespace is ignored. Points have the form “[x,y]” or “O”, while polynomials have the form “[a0,…,an]”. Returns number of characters read (unlike GMP’s mpz_set_str). A return code of zero means PBC could not find a well-formed string describing an element.
2.8. Random elements
Only works for finite algebraic structures. Effect on polynomial rings, fields of characteristic zero, etc. undefined.
See Section 6.1 for how PBC gets random bits.
僅適用於有限的代數結構。 未定義對多項式環，特徵零域等的影響。
有關PBC如何獲取隨機位的信息，請參見第6.1節。
void element_random(element_t e)
If the e lies in a finite algebraic structure, assigns a uniformly random element to e.
如果e位於有限的代數結構中，則將均勻隨機元素分配給e。
2.9. Element import/export
Functions for serializing and deserializing elements.
進行元素序列化和元素反序列化的函數。
int element_length_in_bytes(element_t e)
Returns the length in bytes the element e will take to represent
返回元素e的字節長度；
int element_to_bytes(unsigned char *data, element_t e)
Converts e to byte, writing the result in the buffer data. The number of bytes it will write can be determined from callingelement_length_in_bytes(). Returns number of bytes written.
把元素e轉化爲字節，並把結果寫到緩存區數據。通過調用函數element_length_in_bytes()來確定寫入的字節數。並返回寫入的字節數。
int element_from_bytes(element_t e, unsigned char *data)
Reads e from the buffer data, and returns the number of bytes read.
從緩衝區數據讀取e，並且返回讀取的字節數。
int element_to_bytes_x_only(unsigned char *data, element_t e)
Assumes e is a point on an elliptic curve. Writes the x-coordinate of e to the buffer data
假設e是橢圓曲線上的一個點。把e的x座標寫到緩衝區數據。
int element_from_bytes_x_only(element_t e, unsigned char *data)
Assumes e is a point on an elliptic curve. Sets e to a point with x-coordinate represented by the buffer data. This is not unique.For each x-coordinate, there exist two different points,at least for the elliptic curves in PBC. (They are inverses of each other.)
假設e是一個橢圓曲線上的點。根據緩衝區數據所存儲的x座標來設置e的值。這個值並不是唯一的。對於每個x座標，在PBC的橢圓曲線上都至少有兩個不同的點與之對應。（它們是互爲倒數）
int element_length_in_bytes_x_only(element_t e)
Assumes e is a point on an elliptic curve. Returns the length in bytes needed to hold the x-coordinate of e.
假設e是一個橢圓曲線上的點。返回存儲e的x座標所需要的字節長度。
int element_to_bytes_compressed(unsigned char *data, element_t e)
If possible, outputs a compressed form of the element e to the buffer of bytes data.Currently only implemented for points on an elliptic curve.
如果可以的話，輸出一個。
intelement_from_bytes_compressed(element_t e, unsigned char *data)
Sets element e to the element in compressed form in the buffer of bytes data. Currently only implemented for points on an elliptic curve.
int element_length_in_bytes_compressed(element_t e)
Returns the number of bytes needed to hold e in compressed form. Currently only implemented for points on an elliptic curve.
int element_item_count(element_t e)
For points, returns the number of coordinates. For polynomials, returns the number of coefficients. Otherwise returns zero.
element_telement_item(element_t e, int i)
For points, returns nth coordinate. For polynomials, returns coefficient of xn. Otherwise returns NULL. The element the return value points to may be modified.
element_telement_x(element_t a)
Equivalent to element_item(a, 0).
element_telement_y(element_t a)
Equivalent to element_item(a, 1).
