.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Hashcash 3"
.TH Hashcash 3 "2005-08-02" "perl v5.8.5" "User Contributed Perl Documentation"
.SH "NAME"
Digest::Hashcash \- generate Hashcash stamps (http://www.hashcash.org)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Digest::Hashcash;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements the hashcash hash (or digest, although it's
not clearly a digest). For all your information needs please visit
http://www.hashcash.org.
.PP
One thing to note about this module is that it requires \s-1ISO\s0 C99
support, both in your compiler and your standard library.  If you
don't have a compiler that supports \s-1ISO\s0 C, get gcc at
http://gcc.gnu.org/ :)
.ie n .IP "$secs = estimate_time $size" 4
.el .IP "$secs = estimate_time \f(CW$size\fR" 4
.IX Item "$secs = estimate_time $size"
Estimate the average time necessary to calculate a token of the given
size.
.Sp
See also \f(CW\*(C`estimate_size\*(C'\fR.
.ie n .IP "$size = estimate_size $time\fR[, \f(CW$min]" 4
.el .IP "$size = estimate_size \f(CW$time\fR[, \f(CW$min\fR]" 4
.IX Item "$size = estimate_size $time[, $min]"
Estimate the size that can be calculated in the given time (which is an
upper bound). The function will not return a size less then \f(CW\*(C`min\*(C'\fR.
.Sp
Estimating the time to be used can go wrong by as much as 50% (but is
usually quite accurate), and the estimation itself can take as much as a
second on slower (<pentium) machines, but faster machines (1Ghz P3 for
example) usually handle it within a hundredth of a second or so.
.Sp
The estimation will be done only once, so you can call this fucntion as
often as you like without incuring the overhead everytime.
.IP "$cipher = new Digest::Hashcash [param => value...]" 4
.IX Item "$cipher = new Digest::Hashcash [param => value...]"
.RS 4
.PD 0
.IP "size => 20" 4
.IX Item "size => 20"
.PD
The number of collisions, in bits. Every bit increases the time to create
the token (and thus the cash) by two.
.IP "vers => 1" 4
.IX Item "vers => 1"
Default version 1.  Can produce version 0 if required for backwards
compatibility.
.ie n .IP "uid => """"" 4
.el .IP "uid => ``''" 4
.IX Item "uid => """""
A string used to make the token more unique (e.g. the senders address)
and reduce token collisions. The string must only contain characters
valid for the trial part of the token, e.g. uuencoded, base64 or
e\-mail-address-parts are useful here.  Deprecated: use extension field
if required.
.IP "extrarand => 0" 4
.IX Item "extrarand => 0"
The extra bytes of randomness to add to the token in addition to the
standard amount. Each byte adds a little bit over 6 bit of randomness to
the token.
.Sp
The standard amount of randomness is 8 (> 51 bits of randomness).
.IP "timestamp => 0" 4
.IX Item "timestamp => 0"
The timestamp to use. A value of 0 (the default) means to use the current
time.
.RE
.RS 4
.RE
.ie n .IP "$token = $cipher\->hash ($data [, param => value...])" 4
.el .IP "$token = \f(CW$cipher\fR\->hash ($data [, param => value...])" 4
.IX Item "$token = $cipher->hash ($data [, param => value...])"
Creates and returns a new token. This can take some time.
.Sp
Any additional parameters are interpreted the same way as arguments to
\&\f(CW\*(C`new\*(C'\fR.
.ie n .IP "$prefix = $cipher\->verify ($token)" 4
.el .IP "$prefix = \f(CW$cipher\fR\->verify ($token)" 4
.IX Item "$prefix = $cipher->verify ($token)"
Version 0: Checks the given token and returns the number of collision
bits.
.Sp
Version 1: Returns 0 if stated value is more than the computed
collision value, otherwise returns the stated stamp value.
.Sp
Any additional parameters are interpreted the same way as arguments to
\&\f(CW\*(C`new\*(C'\fR.
.ie n .IP "$version = $cipher\->version ($token)" 4
.el .IP "$version = \f(CW$cipher\fR\->version ($token)" 4
.IX Item "$version = $cipher->version ($token)"
Returns the version of the stamp (currently 0 or 1).
.ie n .IP "$resource = $cipher\->resource ($token)" 4
.el .IP "$resource = \f(CW$cipher\fR\->resource ($token)" 4
.IX Item "$resource = $cipher->resource ($token)"
Returns the resource part, or \f(CW\*(C`undef\*(C'\fR.
.ie n .IP "$tstamp = $cipher\->timestamp ($token)" 4
.el .IP "$tstamp = \f(CW$cipher\fR\->timestamp ($token)" 4
.IX Item "$tstamp = $cipher->timestamp ($token)"
Returns the timestamp part (in the same format as perls \f(CW\*(C`time\*(C'\fR), or
\&\f(CW\*(C`undef\*(C'\fR.
.ie n .IP "$extension = $cipher\->extension ($token [,$name [,$var]])" 4
.el .IP "$extension = \f(CW$cipher\fR\->extension ($token [,$name [,$var]])" 4
.IX Item "$extension = $cipher->extension ($token [,$name [,$var]])"
For Version 1 stamps returns the extension part; for Version 0 stamps
returns undef.  In a scalar context returns the extension string, in
array context returns associative array containing extensions as keys
and their values as the corresponding value.  If the optional name
argument is given, returns info but about that extension (ie decodes
the options of that extension if called in array context); finally if
the optional var argument also is given reports just the (scalar)
value of that variable in the named extension.
.Sp
Note it is valid for an extension to exist (the key exists in the
associative array) but to have undefined value, this corresponds to a
boolean option without a value.  Like \*(L"noreply;foo=bar\*(R" has two
extensions, noreply and foo; noreply has no associated value, so the
method extension would parse such a stamp into an associative array
containing key \*(L"noreply\*(R" with an undefined value; and key \*(L"foo\*(R"
containing associated value \*(L"bar\*(R".
.SH "BUGS"
.IX Header "BUGS"
.Vb 5
\& * There is a y2k+100 problem, as I always assume the same as
\&   Time::Local.  This is a problem with the hashcash specification,
\&   which specifies years as 2 digits :( Though it hardly matters --
\&   after 100 years of Moore's law a 20 bit stamp will be tiny and not
\&   worth storing.
.Ve
.PP
.Vb 2
\& * extension method could be more efficient (it does not cache its
\&   parsed results so if used in a loop reparses on each call)
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 2
\& Marc Lehmann <schmorp@schmorp.de>
\& http://home.schmorp.de
.Ve
.PP
.Vb 2
\& Adam Back <adam@cypherspace.org> added version 1 support
\& http://www.cypherspace.org/adam/
.Ve