view release on metacpan or  search on metacpan

lib/Crypt/PBC/Element.pod  view on Meta::CPAN

    # here, $a and $b will test equal with $a->is_eq( $b )

Assume all the following variables are elements in the indicated groups.  Beware
that the RHS-a elements must all be the same type as the LHS element.  The RHS-n
arguments must all be of elements in Zr.  L<Crypt::PBC::Element> will C<croak()>
an error if the arguments are of the wrong types.

    $G1_l->pow_zn( $Zr_n ); # G1_l = G1_l^Zr_n
    $G1_l->pow_zn( $G1_a, $Zr_n ); # G1_l = G1_a^Zr_n

    $G1_l->pow2_zn( $G1_a1, $Zr_n1, $G1_a2, $Zr_n2 ); # l = a1^n1 * a2^n2
    $G1_l->pow3_zn( $G1_a1, $Zr_n1, $G1_a2, $Zr_n2, $G1_a3, $Zr_n3 );
      # l = a1^n1 * a2^n2 * a3^n3

These functions are all pretty much the same, but they take bigints for the
RHS-n arguments.  They will all C<croak()> if the LHS doesn't match the RHS-a or
if the RHS-n arguments aren't L<Math::BigInt> objects.

    $G1_l->pow_bigint( $G1_a, $BI_n );
    $G1_l->pow2_bigint( $G1_a1, $BI_n1, $G1_a2, $BI_n2 );
    $G1_l->pow3_bigint( $G1_a1, $BI_n1, $G1_a2, $BI_n2, $G1_a3, $BI_n3 );

Arguably the most important arithmetic function of all is saved for last.  The
C<pairing_apply> function is special, in that it has more restrictions on the
LHS, RHS1 and RHS2 than most other functions.  The LHS must be in GT, RHS1 must
be in G1 and RHS2 must be in G2.

    my $GT = $pairing->init_GT;
    my $G1 = $pairing->init_G1;
    my $G2 = $pairing->init_G2;

    $GT->pairing_apply( $G1, $G2 ); 
    $GT->apply_pairing( $G1, $G2 ); # synonym for pairing_apply
    $GT->ehat(  $G1, $G2 );         # synonym for pairing_apply
    $GT->e_hat( $G1, $G2 );         # synonym for pairing_apply

=head1 I/O, Export, and Conversion Functions

libpbc offers a va_args (printf) style output that's probably of limited use
except for debugging.  L<Crypt::PBC> ports the C<fprintf()> version directly
and you can use it as incdicated in L<Crypt::PBC>.  The L<Crypt::PBC::Element>
module only uses C<fprintf()> in the stddump and C<stddump()> and C<errdump()>
and even then only in a limited capacity.
 
    my $element = $pairing->init_G1;
    print "Hey, these don't look like I thought they would:\n";

    $element->stddump; # dumps the element on STDOUT

    # You may be surprised to see that a G1 Element is in fact two MPZs.

    $element->errdump; # dumps the element on STDERR instead of STDOUT

The following will be of major importance to anyone looking to use Crypt::PBC
for real-life applications.  C<as_bytes()> almost certainly has to be used in
conjunction with some other algorithm, but that is indeed what it is for.

    my $secret_key_bin = $element->as_bytes;

    my $example_cipher = new Crypt::CBC({
        header => "randomiv", 
        cipher => 'Blowfish'
        key    => $secret_key_bin,
    });

    my $secret = $example_cipher->encrypt("you can't read this!!");

There are, of course, other ways to export the bytes.  The bigint exporter
probably only works on Zr elements, but it probalby has uses.

    my $key_hex = $element->as_hex;    # as_str is a synonym for as_hex
    my $key_b64 = $element->as_base64; # MIME base64 as per RFC 2045
    my $bigint  = $element->as_bigint; # Math::BigInt

=head1 Miscellaneous Functions

    my $z = $pairing->init_Zr->random;
    my $c = $z->clone;# creates a copy of $z in $c.
    my $d = $z->copy; # copy is an alias for clone
    # ($c is a new Element in new memory with the same value as $z)

=head1 AUTHOR AND LICENSING

GPL-ish licensing with the author: Paul Miller <jettero@cpan.org>.

Please see L<Crypt::PBC> for further information.