Digest-Hashcash/Hashcash.pm

=head1 NAME

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

=head1 SYNOPSIS

 use Digest::Hashcash;

=head1 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/ :)

=over 4

=cut

package Digest::Hashcash;

use Time::Local;

require XSLoader;

no warnings;

$VERSION = 0.01;

XSLoader::load Digest::Hashcash, $VERSION;

=item $cipher = new [param => value...]

=over 4

=item size => 20 + some

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

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

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

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

=item timestamp => 0

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

=back

=item $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
C<new>.

=item $prefix = $cipher->verify($token [, param => value...]))

Checks the given token and returns true if the token has the minimum
number of prefix bits, or false otherwise.  The value returned is actually
the number of collisions, so to find the number of collisions bits specify
C<< collisions => 0 >>.

Any additional parameters are interpreted the same way as arguments to
C<new>.

=item $resource = $cipher->resource($token)

Returns the resource part, or C<undef>.

=item $tstamp = $ciper->timestamp($token)

Returns the timestamp part (in the same format as perl's C<time>), or
C<undef>.

=back

=cut

sub new {
   my $class = shift;

   bless { @_ }, $class;
}

sub hash {
   my $self = shift;
   my %arg = (%$self, resource => @_);

   &_gentoken(@arg{qw(size timestamp resource uid extrarand)});
}

sub verify {
   my ($self, $token) = (shift, shift);
   my %arg = (%$self, @_);

   my $prefix = &_prefixlen($token);

   $prefix < $arg{size}
      ? undef
      : $prefix;
}

sub resource {
   my ($self, $token) = @_;

   $token =~ /^\d+:\d*:(.*):/
      or return undef;

   return $1;
}

sub timestamp {
   my ($self, $token) = @_;

   $token =~ /^\d+:(\d*):.*:/
      or return undef;

   my ($y, $m, $d, $H, $M, $S);
   local $_ = $1;
   $y = /\G(\d\d)/gc ? $1 : return undef;
   $m = /\G(\d\d)/gc ? $1 : 1;
   $d = /\G(\d\d)/gc ? $1 : 1;
   $H = /\G(\d\d)/gc ? $1 : 0;
   $M = /\G(\d\d)/gc ? $1 : 0;
   $S = /\G(\d\d)/gc ? $1 : 0;

   return timegm $S, $M, $H, $d, $m - 1, $y;
}

=head1 SEE ALSO

L<http://www.hashcash.org>.

=head1 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
   yeras as 2 digits :(

=head1 AUTHOR

 Marc Lehmann <pcg@goof.com>
 http://home.schmorp.de

=cut

1;

Revision:	1.1
Committed:	Sat Sep 6 22:12:00 2003 UTC (20 years, 8 months ago) by root
Branch:	MAIN
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			Digest::Hashcash - generate Hashcashes (http://www.hashcash.org)
4
5			=head1 SYNOPSIS
6
7			use Digest::Hashcash;
8
9			=head1 DESCRIPTION
10
11			This module implements the hashcash hash (or digest, although it's
12			not clearly a digest). For all your information needs please visit
13			http://www.hashcash.org.
14
15			One thing to note about this module is that it requires ISO C99 support,
16			both in your compiler and your standard library. If you don't have a
17			compiler that supports ISO C, get gcc at http://gcc.gnu.org/ :)
18
19			=over 4
20
21			=cut
22
23			package Digest::Hashcash;
24
25			use Time::Local;
26
27			require XSLoader;
28
29			no warnings;
30
31			$VERSION = 0.01;
32
33			XSLoader::load Digest::Hashcash, $VERSION;
34
35			=item $cipher = new [param => value...]
36
37			=over 4
38
39			=item size => 20 + some
40
41			The number of collisions, in bits. Every bit increases the time to create
42			the token (and thus the cash) by two.
43
44			=item uid => ""
45
46			A string used to make the token more unique (e.g. the senders address)
47			and reduce token collisions. The string must only contain characters
48			valid for the trial part of the token, e.g. uuencoded, base64 or
49			e-mail-address-parts are useful here.
50
51			=item extrarand => 0
52
53			The extra bytes of randomness to add to the token in addition to the
54			standard amount. Each byte adds a little bit over 6 bit of randomness to
55			the token.
56
57			The standard amount of randomness is 8 (> 51 bits of randomness).
58
59			=item timestamp => 0
60
61			The timestamp to use. A value of 0 (the default) means to use the current
62			time.
63
64			=back
65
66			=item $token = $cipher->hash($data [, param => value...])
67
68			Creates and returns a new token. This can take some time.
69
70			Any additional parameters are interpreted the same way as arguments to
71			C<new>.
72
73			=item $prefix = $cipher->verify($token [, param => value...]))
74
75			Checks the given token and returns true if the token has the minimum
76			number of prefix bits, or false otherwise. The value returned is actually
77			the number of collisions, so to find the number of collisions bits specify
78			C<< collisions => 0 >>.
79
80			Any additional parameters are interpreted the same way as arguments to
81			C<new>.
82
83			=item $resource = $cipher->resource($token)
84
85			Returns the resource part, or C<undef>.
86
87			=item $tstamp = $ciper->timestamp($token)
88
89			Returns the timestamp part (in the same format as perl's C<time>), or
90			C<undef>.
91
92			=back
93
94			=cut
95
96			sub new {
97			my $class = shift;
98
99			bless { @_ }, $class;
100			}
101
102			sub hash {
103			my $self = shift;
104			my %arg = (%$self, resource => @_);
105
106			&_gentoken(@arg{qw(size timestamp resource uid extrarand)});
107			}
108
109			sub verify {
110			my ($self, $token) = (shift, shift);
111			my %arg = (%$self, @_);
112
113			my $prefix = &_prefixlen($token);
114
115			$prefix < $arg{size}
116			? undef
117			: $prefix;
118			}
119
120			sub resource {
121			my ($self, $token) = @_;
122
123			$token =~ /^\d+:\d:(.):/
124			or return undef;
125
126			return $1;
127			}
128
129			sub timestamp {
130			my ($self, $token) = @_;
131
132			$token =~ /^\d+:(\d):.:/
133			or return undef;
134
135			my ($y, $m, $d, $H, $M, $S);
136			local $_ = $1;
137			$y = /\G(\d\d)/gc ? $1 : return undef;
138			$m = /\G(\d\d)/gc ? $1 : 1;
139			$d = /\G(\d\d)/gc ? $1 : 1;
140			$H = /\G(\d\d)/gc ? $1 : 0;
141			$M = /\G(\d\d)/gc ? $1 : 0;
142			$S = /\G(\d\d)/gc ? $1 : 0;
143
144			return timegm $S, $M, $H, $d, $m - 1, $y;
145			}
146
147			=head1 SEE ALSO
148
149			L<http://www.hashcash.org>.
150
151			=head1 BUGS
152
153			* There is a y2k+100 problem, as I always assume the same as Time::Local.
154			This is a problem with the hashcash specification, which specifies
155			yeras as 2 digits :(
156
157			=head1 AUTHOR
158
159			Marc Lehmann <pcg@goof.com>
160			http://home.schmorp.de
161
162			=cut
163
164			1;
165