Crypt::PBC 0.7.20.0-0.4.9

Crypt::PBC is a OO interface for the Stanford PBC library.

SYNOPSIS

use Crypt::PBC;

my $pairing = new Crypt::PBC("params_d.txt");
my $G1 = $pairing->init_G1->random;
my $G2 = $pairing->init_G2->random->double->square;
my $GT = $pairing->init_GT->pairing_apply( $G1, $G2 );

The PBC library is a free portable C library designed to make it easy to implement pairing-based cryptosystems. It provides an abstract interface to a cyclic group with a bilinear pairing, and the programmer does not need to worry about, or even know about elliptic curves.

It is built on top of GMP, another C library which performs arbitrary precision arithmetic on integers, rationals and floats with strong emphasis on portability and speed.

Perl Module Methods

The Perl Module methods implement an OO interface that the author (Paul) highly recommends using. The only Perl Module OO function in the Crypt::PBC package is new(). Please see Crypt::PBC::Pairing and Crypt::PBC::Element for the guts of the intended OO interface.

Crypt::PBC::new()

Returns a new PBC pairing object. new() takes, as arguments, either the name of a file, a file stream (e.g., new Crypt::PBC(*STDIN)), or the params for a curve as a string. Ben Lynn provides a zip file of d-type curves:

MNT curve parameters for embedding degree 6 (which I
call type D curves), for all D less than a million, and
for subgroup sizes at least 80 bits and less than 300
bits long. Generated using test programs bundled with
PBC library.

http://crypto.stanford.edu/pbc/download.html

XS Loaded Functions

This section is basically a listing of the PBC functions as they are imported. You can use them directly if youre already comfortable with the layout of PBC. If youre starting from scratch and arent much of a C coder, youll have an easier time using the Perl Module methods because they implement a little type-safety to protect perl coders from segfaults.

Mixing and matching direct calls with the Perl Module methods is a sure way to run into trouble, since the Perl Module methods tag the PBC elements with a type.

+++ NOTE +++
You can use these functions successfully, but the intended interface was described above. Crypt::PBC::Element describes that interface in detail.
+++ /NOTE +++

Pairing Functions

# Initialize a pairing from an open file handle
my $pairing = &Crypt::PBC::pairing_init_stream(*STDIN);

# Initialize a pairing from a a $string
my $pairing = &Crypt::PBC::pairing_init_str($string);

# Clear the memory malloced for the pairing
&Crypt::PBC::pairing_clear($pairing);

# Apply the pairing. Be careful here. If you pass the wrong type of
# elements, GT = apply(G1, G2), this will segmentation fault! Please
# see the PBC documentation for further information:
# http://crypto.stanford.edu/pbc/manual/
&Crypt::PBC::pairing_apply($LHS, $RHS1, $RHS2, $pairing);

Element Initializer and Assignment Functions

my $element_in_G1 = &Crypt::PBC::element_init_G1($pairing);
my $element_in_G2 = &Crypt::PBC::element_init_G2($pairing);
my $element_in_GT = &Crypt::PBC::element_init_GT($pairing);
my $element_in_Zr = &Crypt::PBC::element_init_Zr($pairing);

# Do not forget to clear your memory!
&Crypt::PBC::element_clear( $element ); # in any group

# assign some random to $element
# (uses /dev/urandom if possible, or rand() if necessary)
&Crypt::PBC::element_random( $element );
&Crypt::PBC::element_set0( $element ); # set to 0
&Crypt::PBC::element_set1( $element ); # set to 1
&Crypt::PBC::element_set( $a, $b ); # a=b
&Crypt::PBC::element_set_si( $a, 5 ); # a=5

&Crypt::PBC::element_set_mpz( $a, $bigint );
# For this one, construct a Math::BigInt::GMP and pass that for
# $bigint. Alternatively, you can construct a $i=Math::BigInt and
# pass the $i->{value}. (That interface is probably not well
# supported but is the only one of which the author is aware.)

&Crypt::PBC::element_from_hash( $element, $hash );
# Set $element based on the bytes in $hash. You must use some kind
# of hashing algorithm (e.g., Digest::SHA1) to map data to an
# element:
#
# "In general you cannot feed it plaintext. You should only give it
# short strings of bytes (e.g. 160 bits if G1 has order around 2^160,
# which is the case for most of the bundled pairing parameters)."
# -- Lynn

&Crypt::PBC::element_from_bytes( $element, $bytes );
# Set $element based on the bytes in $bytes. this probably isnt useful
# unless $bytes is like $spewed_result from element_export() below.

Arithmetic Functions

# lhs=rhs1+rhs2 -- make sure these are all the same type ...
&Crypt::PBC::element_add($lhs, $rhs1, $rhs2);
&Crypt::PBC::element_sub($lhs, $rhs1, $rhs2); # lhs=rhs1-rhs2
&Crypt::PBC::element_mul($lhs, $rhs1, $rhs2);
&Crypt::PBC::element_div($lhs, $rhs1, $rhs2);

# (whatever these mean is in the context of the $pairing)
&Crypt::PBC::element_double($lhs, $rhs); # lhs = 2*rhs
&Crypt::PBC::element_halve( $lhs, $rhs); # lhs = rhs/2
&Crypt::PBC::element_square($lhs, $rhs); # lhs = rhs^2
&Crypt::PBC::element_neg( $lhs, $rhs); # (please see the PBC docs)
&Crypt::PBC::element_invert($lhs, $rhs); # lhs = 1/rhs

# Heres a few other choices for mul
&Crypt::PBC::element_mul_zn( $lhs, $rhs1, $rhs2 );
# $rhs1 and $lhs should be of the same type, but here $rhs2 should be
# in Zr instead of being in the same group like in element_mul()
# above

&Crypt::PBC::element_mul_mpz( $lhs, $rhs1, $rhs2 );
# For this one, construct a Math::BigInt::GMP and pass that for
# $rhs2 or pass $i->{value} from a Math::BigInt.

&Crypt::PBC::element_mul_si( $lhs, $rhs1, $rhs2 );
# Here, $rhs2 is a regular old integer...

&Crypt::PBC::element_pow_zn( $lhs, $a, $n); # lhs = a^n
&Crypt::PBC::element_pow2_zn($lhs, $a1, $n1, $a2, $n2); # a1^n1 * a2^n2
&Crypt::PBC::element_pow3_zn($lhs, $a1, $n1, $a2, $n2, $a3, $n3);
# in the above, the lhs and ad+ should be in the same group, nd+ in Zr

&Crypt::PBC::element_pow_mpz( $lhs, $a, $n);
&Crypt::PBC::element_pow2_mpz($lhs, $a1, $n1, $a2, $n2);
&Crypt::PBC::element_pow3_mpz($lhs, $a1, $n1, $a2, $n2, $a3, $n3);
# like the _zn functions, but nd+ should be Math::BigInt::GMP
# or pass $i->{value} from a Math::BigInt.

Comparison Functions

&Crypt::PBC::element_is0( $a ); # 1 when $a is 0
&Crypt::PBC::element_is1( $a ); # 1 when $a is 1
&Crypt::PBC::element_cmp( $a,$b ); # paradoxically, false when $a == $b
&Crypt::PBC::element_is_sqr( $a ); # 1 when $a is a perfect square ...
# see the PBC docs for words like "residue"

Export and Output

# Please check the PBC docs ...
&Crypt::PBC::element_fprintf(*OUTFILE, $format, $element);
&Crypt::PBC::element_fprintf(*STDOUT, "example element=%Bn", $element);
# (You may be surprised how many bigints are in these group elements.)

my $spewed_result = &Crypt::PBC::export_element($element);
# These are bytes, dumped from the $element, that can be used to
# reconstruct the element or used for interacting with real life data.

# Example:
my $cipher = new Crypt::CBC({
header => "randomiv",
key => &Crypt::PBC::export_element($element),
cipher => Blowfish, # hehe
});

my $big = &Crypt::PBC::element_to_mpz( $element );
# Returns a Math::BigInt::GMP, not a Math::BigInt! WARNING: the
# DESTROY() method from Math::BigInt::GMP will be missing unless you
# require that package into your program. Youll want to do that or youll
# have a memory leak... Lastly, this is really only useful for elements in
# Zr -- element_fprintf() to see what I mean.