view release on metacpan or  search on metacpan

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

    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

    # Here's 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 a\d+ should be in the same group, n\d+ 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 n\d+ should be Math::BigInt::GMP
      # or pass $i->{value} from a Math::BigInt.

=head2 Comparison Functions

(You can use these functions successfully, but the intended interface was
described above. L<Crypt::PBC::Element> describes that interface in detail.)

    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"

=head2 Export and Output

(You can use these functions successfully, but the intended interface was
described above. L<Crypt::PBC::Element> describes that interface in detail.)

    # Please check the PBC docs ...
    Crypt::PBC::element_fprintf(\*OUTFILE, $format, $element);
    Crypt::PBC::element_fprintf(\*STDOUT, "example element=\%B\n", $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.  You'll want to do that or you'll
    # have a memory leak...  Lastly, this is really only useful for elements in
    # Zr -- element_fprintf() to see what I mean.

=head1 XS AUTHOR

Paul Miller <jettero@cpan.org>

Paul is using this software in his own projects...  If you find bugs, please
please please let him know. :) Actually, let him know if you find it handy at
all.  Half the fun of releasing this stuff is knowing that people use it.

Additionally, he is aware that the documentation sucks.  Should you email him
for help, he will most likely try to give it.

=head1 COPYRIGHT

Copyright (c) 2008 Paul Miller -- LGPL [attached]

This interface is intended to be LGPL to whatever extent allowed by the license
for the pbc library itself.  That license is GPL and probably therefore makes
this package GPL.  I'm not expert on these matters, so I'm choosing LGPL if
possible.

=head1 SPECIAL THANKS

Without the direction of Dr. Leszek T. Lilien
(http://www.cs.wmich.edu/~llilien/), I never would have heard of IBE/PBC --
much less develop any interest in it.  Crypto is not his specialty, but
like any good professor, he's interested in everything.

=head1 SEE ALSO

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

    http://groups.google.com/group/pbc-devel

perl(1), L<Crypt::PBC::Pairing>, L<Crypt::PBC::Element>