.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Crypt::DH::GMP 3pm"
.TH Crypt::DH::GMP 3pm "2020-11-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Crypt::DH::GMP \- Crypt::DH Using GMP Directly
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Crypt::DH::GMP;
\&
\&  my $dh = Crypt::DH::GMP\->new(p => $p, g => $g);
\&  my $val = $dh\->compute_secret();
\&
\&  # If you want compatibility with Crypt::DH (it uses Math::BigInt)
\&  # then use this flag
\&  # You /think/ you\*(Aqre using Crypt::DH, but...
\&  use Crypt::DH::GMP qw(\-compat);
\&
\&  my $dh = Crypt::DH\->new(p => $p, g => $g);
\&  my $val = $dh\->compute_secret();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Crypt::DH::GMP is a (somewhat) portable replacement to Crypt::DH, implemented
mostly in C.
.SH "RATIONALE"
.IX Header "RATIONALE"
In the beginning, there was \f(CW\*(C`Crypt::DH\*(C'\fR. However, \f(CW\*(C`Crypt::DH\*(C'\fR suffers
from a couple of problems:
.IP "GMP/Pari libraries are almost always required" 4
.IX Item "GMP/Pari libraries are almost always required"
\&\f(CW\*(C`Crypt::DH\*(C'\fR works with a plain \f(CW\*(C`Math::BigInt\*(C'\fR, but if you want to use
it in production, you almost always need to install \f(CW\*(C`Math::BigInt::GMP\*(C'\fR
or \f(CW\*(C`Math::BigInt::Pari\*(C'\fR because without them, the computation that is
required by \f(CW\*(C`Crypt::DH\*(C'\fR makes the module pretty much unusable.
.Sp
Because of this, \f(CW\*(C`Crypt::DH\*(C'\fR might as well make \f(CW\*(C`Math::BigInt::GMP\*(C'\fR a
hard requirement.
.IP "Crypt::DH suffers from having Math::BigInt in between \s-1GMP\s0" 4
.IX Item "Crypt::DH suffers from having Math::BigInt in between GMP"
With or without \f(CW\*(C`Math::BigInt::GMP\*(C'\fR or \f(CW\*(C`Math::BigInt::Pari\*(C'\fR, \f(CW\*(C`Crypt::DH\*(C'\fR
makes several round trip conversions between Perl scalars, Math::BigInt objects,
and finally its C representation (if GMP/Pari are installed).
.Sp
Instantiating an object comes with a relatively high cost, and if you make
many computations in one go, your program will suffer dramatically because
of this.
.PP
These problems quickly become apparent when you use modules such as 
\&\f(CW\*(C`Net::OpenID::Consumer\*(C'\fR, which requires to make a few calls to \f(CW\*(C`Crypt::DH\*(C'\fR.
.PP
\&\f(CW\*(C`Crypt::DH::GMP\*(C'\fR attempts to alleviate these problems by providing a 
\&\f(CW\*(C`Crypt::DH\*(C'\fR\-compatible layer, which, instead of doing calculations via
Math::BigInt, directly works with libgmp in C.
.PP
This means that we've essentially eliminated 2 call stacks worth of 
expensive Perl method calls and we also only load 1 (Crypt::DH::GMP) module
instead of 3 (Crypt::DH + Math::BigInt + Math::BigInt::GMP).
.PP
These add up to a fairly significant increase in performance.
.SH "COMPATIBILITY WITH Crypt::DH"
.IX Header "COMPATIBILITY WITH Crypt::DH"
Crypt::DH::GMP absolutely refuses to consider using anything other than
strings as its parameters and/or return values therefore if you would like
to use Math::BigInt objects as your return values, you can not use 
Crypt::DH::GMP directly. Instead, you need to be explicit about it:
.PP
.Vb 2
\&  use Crypt::DH;
\&  use Crypt::DH::GMP qw(\-compat); # must be loaded AFTER Crypt::DH
.Ve
.PP
Specifying \-compat invokes a very nasty hack that overwrites Crypt::DH's
symbol table \*(-- this then forces Crypt::DH users to use Crypt::DH::GMP
instead, even if you are writing
.PP
.Vb 2
\&  my $dh = Crypt::DH\->new(...);
\&  $dh\->compute_key();
.Ve
.SH "BENCHMARK"
.IX Header "BENCHMARK"
By \s-1NO MEANS\s0 is this an exhaustive benchmark, but here's what I get on my
MacBook (\s-1OS X 10.5.8, 2.4\s0 GHz Core 2 Duo, 4GB \s-1RAM\s0)
.PP
.Vb 4
\&  Benchmarking instatiation cost...
\&         Rate   pp  gmp
\&  pp   9488/s   \-\- \-79%
\&  gmp 45455/s 379%   \-\-
\&
\&  Benchmarking key generation cost...
\&        Rate gmp  pp
\&  gmp 6.46/s  \-\- \-0%
\&  pp  6.46/s  0%  \-\-
\&
\&  Benchmarking compute_key cost...
\&          Rate    pp   gmp
\&  pp   12925/s    \-\-  \-96%
\&  gmp 365854/s 2730%    \-\-
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.SS "p"
.IX Subsection "p"
.SS "g"
.IX Subsection "g"
.SS "compute_key"
.IX Subsection "compute_key"
.SS "compute_secret"
.IX Subsection "compute_secret"
.SS "generate_keys"
.IX Subsection "generate_keys"
.SS "pub_key"
.IX Subsection "pub_key"
.SS "priv_key"
.IX Subsection "priv_key"
.SS "compute_key_twoc"
.IX Subsection "compute_key_twoc"
Computes the key, and returns a string that is byte-padded two's compliment
in binary form.
.SS "pub_key_twoc"
.IX Subsection "pub_key_twoc"
Returns the pub_key as a string that is byte-padded two's compliment
in binary form.
.SS "clone"
.IX Subsection "clone"
.SH "AUTHOR"
.IX Header "AUTHOR"
Daisuke Maki \f(CW\*(C`<daisuke@endeworks.jp>\*(C'\fR
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.PP
See http://www.perl.com/perl/misc/Artistic.html