PyPBC

PyPBC is a Python wrapper for the PBC (Pairing-Based Cryptography) library, allowing for easy use of pairing-based cryptography in Python.

Installation

This project follows the common "system dependency + Python wrapper" pattern:

1. Install system dependencies (GMP + PBC)
2. Install the Python package (pypbc)

Install GMP and other dependencies

For Debian / Ubuntu systems, you can use the provided script to install the necessary dependencies for PBC:

sudo scripts/install-pbc-deps-debian

For other systems, you will need to manually install GMP and the build tools (gcc, flex, bison) as described in the PBC installation instructions.

Install PBC

You can use the provided script to install the PBC library:

sudo scripts/install-pbc

Install pypbc

Once GMP and PBC are installed, you can install pypbc via pip (for Python v3):

python3 -m pip install .

Basic Usage

The library provides a simple interface to the PBC library, allowing for easy use of pairing-based cryptography in Python. Here is are some examples of how to use the library.

from pypbc import *

# Initialize a set of parameters from a string 
# check the PBC documentation (http://crypto.stanford.edu/pbc/manual/) for more information
params = Parameters(
    "type a\n"
    "q 8780710799663312522437781984754049815806883199414208211028653399266475630880222957078625179422662221423155858769582317459277713367317481324925129998224791\n"
    "h 12016012264891146079388821366740534204802954401251311822919615131047207289359704531102844802183906537786776\n"
    "r 730750818665451621361119245571504901405976559617\n"
    "exp2 159\n"
    "exp1 107\n"
    "sign1 1\n"
    "sign0 1\n"
)

# Initialize the pairing
pairing = Pairing(params)

# show the order of the pairing
print(pairing.order())

# Generate random elements
g1 = Element.random(pairing, G1)
g2 = Element.random(pairing, G2)
z1 = Element.random(pairing, Zr)
z2 = Element.random(pairing, Zr)

# Check the properties of the pairing
assert pairing.apply(g1 ** z1, g2 ** z2) == pairing.apply(g1, g2) ** (z1 * z2)

API Reference

Group Enum

The library defines the following groups:

• Zr: The multiplicative group of integers modulo the order of the pairing.
• G1: The first source group of the pairing.
• G2: The second source group of the pairing.
• GT: The target group of the pairing.

The Following classes and methods are available:

Parameters

• __init__(self, string: str) -> None: Initialize the parameters from a string.
• __str__(self) -> str: Return the string representation of the parameters.

Pairing

• __init__(self, params: Parameters) -> None: Initialize the pairing from the given parameters.
• order(self) -> int: Return the order of the pairing (Zr, G1, G2 and GT).
• apply(self, e1: Element, e2: Element) -> Element: Apply the pairing to the given elements.
• is_symmetric(self) -> bool: Return whether the pairing is symmetric.

Element

Constructors

• __init__(self, pairing: Pairing, type: Group, string: str) -> None: Initialize the element from a string representation.
• from_int(pairing: Pairing, value: int) -> Element: Return an element in Zr from the given integer.
• random(pairing: Pairing, type: Group) -> Element: Return a random element of the given type.
• zero(pairing: Pairing, type: Group) -> Element: Return the additive identity element of the given type.
• one(pairing: Pairing, type: Group) -> Element: Return the multiplicative identity element of the given type.
• from_hash(pairing: Pairing, type: Group, data: bytes) -> Element: Return an element from the given hash.

Serialize and Deserialize

• to_bytes(self) -> bytes: Return the byte representation of the element.
• to_bytes_compressed(self) -> bytes: Return the compressed byte representation of the element. (Only for G1 and G2 elements)
• to_bytes_x_only(self) -> bytes: Return the x-only byte representation of the element. (Only for G1 and G2 elements)
• from_bytes(pairing: Pairing, type: Group, data: bytes) -> Element: Return an element from the given byte representation.
• from_bytes_compressed(pairing: Pairing, type: Group, data: bytes) -> Element: Return an element from the given compressed byte representation. (Only for G1 and G2 elements)
• from_bytes_x_only(pairing: Pairing, type: Group, data: bytes) -> Element: Return an element from the given x-only byte representation. (Only for G1 and G2 elements)

Properties

• order(self): Return the order of the element.
• __getitem__(self, index: int) -> Element: Return the i-th item of the element (if it is multidimensional).
• __len__(self) -> int: Return the length of the element, returns 0 if the element is one-dimensional.

Typecasting

• __str__(self) -> str: Return the string representation of the element.
• __int__(self) -> int: Return the integer representation of the element (if possible).

Hashing

• __hash__(self) -> int: Return the hash value of the element.

Arithmetic Operations

• __add__(self, other: Element) -> Element: Return the sum of the elements.
• __sub__(self, other: Element) -> Element: Return the difference of the elements.
• __mul__(self, other: Element | int) -> Element: Return the product of the elements, same as __add__ method if the two operands are both in G1, G2 or GT, and same as __pow__ if one of the operands is an integer or an element of Zr and another is in G1, G2 or GT.
• __truediv__(self, other: Element) -> Element: Return the quotient of the elements, the two operands must be in same field, it is same as __sub__ if the two operands are both in G1, G2 or GT. Notice: Division between elements in G1,G2 or GT and elements in Zr is not allowed.
• __pow__(self, other: Element | int) -> Element: Return the power of the element, the exponent can be an integer or an element of Zr.
• __neg__(self) -> Element: Return the additive inverse of the element.
• __invert__(self) -> Element: Return the multiplicative inverse of the element, same as __neg__ if the element is in G1, G2 or GT.

Comparison Operations

• __eq__(self, other: Element) -> bool: Return whether the elements are equal.
• __ne__(self, other: Element) -> bool: Return whether the elements are not equal.
• is0(self) -> bool: Return whether the element is the additive identity.
• is1(self) -> bool: Return whether the element is the multiplicative identity.

Acknowledgements

This project is based on the original PyPBC project by Geremy Condra.