NAME
    Digest::Hashcash - generate Hashcash stamps (http://www.hashcash.org)

SYNOPSIS
     use Digest::Hashcash;

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.

    One thing to note about this module is that it requires ISO C99 support,
    both in your compiler and your standard library. If you don't have a
    compiler that supports ISO C, get gcc at http://gcc.gnu.org/ :)

    $secs = estimate_time $size
        Estimate the average time necessary to calculate a token of the
        given size.

        See also "estimate_size".

    $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
        "min".

        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.

        The estimation will be done only once, so you can call this fucntion
        as often as you like without incuring the overhead everytime.

    $cipher = new Digest::Hashcash [param => value...]

        size => 20
            The number of collisions, in bits. Every bit increases the time
            to create the token (and thus the cash) by two.

        vers => 1
            Default version 1. Can produce version 0 if required for
            backwards compatibility.

        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.

        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.

            The standard amount of randomness is 8 (> 51 bits of
            randomness).

        timestamp => 0
            The timestamp to use. A value of 0 (the default) means to use
            the current time.

    $token = $cipher->hash ($data [, param => value...])
        Creates and returns a new token. This can take some time.

        Any additional parameters are interpreted the same way as arguments
        to "new".

    $prefix = $cipher->verify ($token)
        Version 0: Checks the given token and returns the number of
        collision bits.

        Version 1: Returns 0 if stated value is more than the computed
        collision value, otherwise returns the stated stamp value.

        Any additional parameters are interpreted the same way as arguments
        to "new".

    $version = $cipher->version ($token)
        Returns the version of the stamp (currently 0 or 1).

    $resource = $cipher->resource ($token)
        Returns the resource part, or "undef".

    $tstamp = $cipher->timestamp ($token)
        Returns the timestamp part (in the same format as perls "time"), or
        "undef".

    $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.

        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 "noreply;foo=bar" 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 "noreply" with an undefined value; and key "foo"
        containing associated value "bar".

BUGS
     * 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.

     * extension method could be more efficient (it does not cache its
       parsed results so if used in a loop reparses on each call)

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de

     Adam Back <adam@cypherspace.org> added version 1 support
     http://www.cypherspace.org/adam/