blib/lib/Digest/Hashcash.pm

filter: Statementstmt 100% 43 / 43 Branchbran 50.0% 10 / 20 Conditioncond 33.3% 1 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 100% 11 / 11 Podpod 100% 7 / 7 totaltotal 83.7% 72 / 86 CC 12 SCAR 15.0
CC
12
Cov
82%
timestamp
9.4
_rounds
2.5
estimate_size
2.0
CRAP 4.5
↑ Summary perlmulticore.h »
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 1 ▶use Time::Local;
Subroutine BEGIN: called CC=1 SCAR=0.0
26 1 ▶use Time::HiRes;
Subroutine BEGIN: called CC=1 SCAR=0.0
27  
28 1 require XSLoader;
29  
30 1 ▶no warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
31  
32 1 $VERSION = 1.1;
33  
34 1 XSLoader::load Digest::Hashcash, $VERSION;
35  
36 =item $secs = estimate_time $size
37  
38 Estimate the average time necessary to calculate a token of the given
39 size.
40  
41 See also C<estimate_size>.
42  
43 =item $size = estimate_size $time[, $min]
44  
45 Estimate the size that can be calculated in the given time (which is an
46 upper bound). The function will not return a size less then C<min>.
47  
48 Estimating the time to be used can go wrong by as much as 50% (but is
49 usually quite accurate), and the estimation itself can take as much as a
50 second on slower (<pentium) machines, but faster machines (1Ghz P3 for
51 example) usually handle it within a hundredth of a second or so.
52  
53 The estimation will be done only once, so you can call this fucntion as
54 often as you like without incuring the overhead everytime.
55  
56 =cut
57  
58 1 my $rounds;
59  
60 1 ▶sub _rounds {
Subroutine _rounds: called CC=2 SCAR=9.2
61 1 ▶ $rounds ||= &_estimate_rounds();
Condition33%1/3
$rounds ||= &_estimate_rounds()
l!l&&r!l&&!r
010
MC/DC0%0/2
$rounds ||= &_estimate_rounds()
$rounds &_estimate_rounds()
Truth table33%1/3
A ||= B
A= $roundsB= &_estimate_rounds()
ABresult
1X1
011
000
62 }
63  
64 1 ▶sub estimate_time {
Subroutine estimate_time: called CC=1 SCAR=0.0
Pod documented
65 1 my ($size) = @_;
66 1 2**$size / &_rounds;
67 }
68  
69 1 ▶sub estimate_size {
Subroutine estimate_size: called CC=2 SCAR=7.1
Pod documented
70 1 my ($time, $min) = @_;
71 1 $time = (log $time * $rounds) / log 2;
72 1 ▶ $time < $min ? $min : int $time;
Branch: 1 branch
BranchTrueFalseTotal
$time < $min ? : 0 1 1
73 }
74  
75 =item $cipher = new Digest::Hashcash [param => value...]
76  
77 =over 4
78  
79 =item size => 18
80  
81 The number of collisions, in bits. Every bit increases the time to create
82 the token (and thus the cash) by two.
83  
84 =item uid => ""
85  
86 A string used to make the token more unique (e.g. the senders address)
87 and reduce token collisions. The string must only contain characters
88 valid for the trial part of the token, e.g. uuencoded, base64 or
89 e-mail-address-parts are useful here.
90  
91 =item extrarand => 0
92  
93 The extra bytes of randomness to add to the token in addition to the
94 standard amount. Each byte adds a little bit over 6 bit of randomness to
95 the token.
96  
97 The standard amount of randomness is 8 (> 51 bits of randomness).
98  
99 =item timestamp => 0
100  
101 The timestamp to use. A value of 0 (the default) means to use the current
102 time.
103  
104 =back
105  
106 =item $token = $cipher->hash ($data [, param => value...])
107  
108 Creates and returns a new token. This can take some time.
109  
110 Any additional parameters are interpreted the same way as arguments to
111 C<new>.
112  
113 =item $prefix = $cipher->verify ($token [, param => value...]))
114  
115 Checks the given token and returns true if the token has the minimum
116 number of prefix bits, or false otherwise. The value returned is actually
117 the number of collisions, so to find the number of collisions bits specify
118 C<< collisions => 0 >>.
119  
120 Any additional parameters are interpreted the same way as arguments to
121 C<new>.
122  
123 =item $resource = $cipher->resource ($token)
124  
125 Returns the resource part, or C<undef>.
126  
127 =item $tstamp = $ciper->timestamp ($token)
128  
129 Returns the timestamp part (in the same format as perl's C<time>), or
130 C<undef>.
131  
132 =back
133  
134 =cut
135  
136 2 ▶sub new {
Subroutine new: called CC=1 SCAR=0.0
Pod documented
137 2 my $class = shift;
138  
139 2 bless { @_ }, $class;
140 }
141  
142 162 ▶sub hash {
Subroutine hash: called CC=1 SCAR=0.0
Pod documented
143 162 my $self = shift;
144 162 my %arg = (%$self, resource => @_);
145  
146 162 &_gentoken(@arg{qw(size timestamp resource uid extrarand)});
147 }
148  
149 166 ▶sub verify {
Subroutine verify: called CC=2 SCAR=7.0
Pod documented
150 166 my ($self, $token) = (shift, shift);
151 166 my %arg = (%$self, @_);
152  
153 166 my $prefix = &_prefixlen($token);
154  
155 $prefix < $arg{size}
156 ? undef
157 166 ▶ : $prefix;
Branch: 1 branch
BranchTrueFalseTotal
$prefix < $arg{'size'} ? : 0 166 166
158 }
159  
160 1 ▶sub resource {
Subroutine resource: called CC=2 SCAR=7.1
Pod documented
161 1 my ($self, $token) = @_;
162  
163 1 ▶ $token =~ /^\d+:\d*:(.*):/
Branch: 1 branch
BranchTrueFalseTotal
$token =~ /^\d+:\d*:(.*):/ or return undef 1 0 1
164 or return undef;
165  
166 1 return $1;
167 }
168  
169 1 ▶sub timestamp {
Subroutine timestamp: called CC=8 SCAR=22.4
Pod documented
170 1 my ($self, $token) = @_;
171  
172 1 ▶ $token =~ /^\d+:(\d*):.*:/
Branch: 1 branch
BranchTrueFalseTotal
$token =~ /^\d+:(\d*):.*:/ or return undef 1 0 1
173 or return undef;
174  
175 1 my ($y, $m, $d, $H, $M, $S);
176 1 local $_ = $1;
177 1 ▶ $y = /\G(\d\d)/gc ? $1 : return undef;
Branch: 1 branch
BranchTrueFalseTotal
/\G(\d\d)/cg ? : 1 0 1
178 1 ▶ $m = /\G(\d\d)/gc ? $1 : 1;
Branch: 1 branch
BranchTrueFalseTotal
/\G(\d\d)/cg ? : 1 0 1
179 1 ▶ $d = /\G(\d\d)/gc ? $1 : 1;
Branch: 1 branch
BranchTrueFalseTotal
/\G(\d\d)/cg ? : 1 0 1
180 1 ▶ $H = /\G(\d\d)/gc ? $1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
/\G(\d\d)/cg ? : 1 0 1
181 1 ▶ $M = /\G(\d\d)/gc ? $1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
/\G(\d\d)/cg ? : 1 0 1
182 1 ▶ $S = /\G(\d\d)/gc ? $1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
/\G(\d\d)/cg ? : 1 0 1
183  
184 1 return timegm $S, $M, $H, $d, $m - 1, $y;
185 }
186  
187 =head1 SEE ALSO
188  
189 L<http://www.hashcash.org>.
190  
191 =head1 SUPPORT FOR THE PERL MULTICORE SPECIFICATION
192  
193 This module supports the perl multicore specification
194 (<http://perlmulticore.schmorp.de/>) for token generation of any length
195 and size.
196  
197 =head1 BUGS
198  
199 * There is a y2k+100 problem, as I always assume the same as Time::Local.
200 This is a problem with the hashcash specification, which specifies
201 years as 2 digits :(
202  
203 =head1 AUTHOR
204  
205 Marc Lehmann <schmorp@schmorp.de>
206 http://home.schmorp.de
207  
208 =cut
209  
210 1 1;
211  
↑ Summary perlmulticore.h »