Profile of /usr/local/lib/perl5/5.10.1/darwin-2level/Digest/SHA.pm

← Index
NYTProf Performance Profile «block view•line view•sub view»
For 05.Domain_and_Item.t
Run on Tue May 4 17:21:41 2010
Reported on Tue May 4 17:22:22 2010

File | /usr/local/lib/perl5/5.10.1/darwin-2level/Digest/SHA.pm
Statements Executed | 32
Statement Execution Time | 1.33ms

Subroutines — ordered by exclusive time
Calls | P | F | Exclusive Time | Inclusive Time | Subroutine
--- | --- | --- | --- | --- | ---
41 | 1 | 2 | 773µs | 773µs | Digest::SHA::::hmac_sha256_base64Digest::SHA::hmac_sha256_base64 (xsub)
1 | 1 | 1 | 172µs | 175µs | Digest::SHA::::BEGIN@6Digest::SHA::BEGIN@6
1 | 1 | 2 | 86µs | 86µs | Digest::SHA::::bootstrapDigest::SHA::bootstrap (xsub)
1 | 1 | 2 | 31µs | 31µs | Digest::SHA::::shaopenDigest::SHA::shaopen (xsub)
1 | 1 | 1 | 29µs | 62µs | Digest::SHA::::newDigest::SHA::new
1 | 1 | 1 | 17µs | 20µs | Digest::SHA::::BEGIN@5Digest::SHA::BEGIN@5
1 | 1 | 1 | 11µs | 77µs | Digest::SHA::::BEGIN@7Digest::SHA::BEGIN@7
1 | 1 | 2 | 2µs | 2µs | Digest::SHA::::CORE:substDigest::SHA::CORE:subst (opcode)
0 | 0 | 0 | 0s | 0s | Digest::SHA::::AddfileDigest::SHA::Addfile
0 | 0 | 0 | 0s | 0s | Digest::SHA::::DESTROYDigest::SHA::DESTROY
0 | 0 | 0 | 0s | 0s | Digest::SHA::::_addfileDigest::SHA::_addfile
0 | 0 | 0 | 0s | 0s | Digest::SHA::::_bailDigest::SHA::_bail
0 | 0 | 0 | 0s | 0s | Digest::SHA::::add_bitsDigest::SHA::add_bits
0 | 0 | 0 | 0s | 0s | Digest::SHA::::cloneDigest::SHA::clone
0 | 0 | 0 | 0s | 0s | Digest::SHA::::dumpDigest::SHA::dump
0 | 0 | 0 | 0s | 0s | Digest::SHA::::loadDigest::SHA::load

Call graph for these subroutines as a Graphviz dot language file.

Line | State ments | Time on line | Calls | Time in subs | Code
--- | --- | --- | --- | --- | ---
1 |  |  |  |  | package Digest::SHA;
2 |  |  |  |  |
3 | 1 | 26µs |  |  | require 5.003000;
4 |  |  |  |  |
5 | 3 | 23µs | 2 | 24µs | # spent 20µs (17+3) within Digest::SHA::BEGIN@5 which was called # once (17µs+3µs) by SimpleDB::Client::BEGIN@52 at line 5 use strict; # spent 20µs making 1 call to Digest::SHA::BEGIN@5 # spent 3µs making 1 call to strict::import
6 | 3 | 184µs | 2 | 177µs | # spent 175µs (172+3) within Digest::SHA::BEGIN@6 which was called # once (172µs+3µs) by SimpleDB::Client::BEGIN@52 at line 6 use integer; # spent 175µs making 1 call to Digest::SHA::BEGIN@6 # spent 3µs making 1 call to integer::import
7 | 3 | 805µs | 2 | 143µs | # spent 77µs (11+66) within Digest::SHA::BEGIN@7 which was called # once (11µs+66µs) by SimpleDB::Client::BEGIN@52 at line 7 use vars qw($VERSION @ISA @EXPORT @EXPORT_OK); # spent 77µs making 1 call to Digest::SHA::BEGIN@7 # spent 66µs making 1 call to vars::import
8 |  |  |  |  |
9 | 1 | 400ns |  |  | $VERSION = '5.47';
10 |  |  |  |  |
11 | 1 | 700ns |  |  | require Exporter;
12 | 1 | 300ns |  |  | require DynaLoader;
13 | 1 | 11µs |  |  | @ISA = qw(Exporter DynaLoader);
14 | 1 | 5µs |  |  | @EXPORT_OK = qw(
15 |  |  |  |  | hmac_sha1 hmac_sha1_base64 hmac_sha1_hex
16 |  |  |  |  | hmac_sha224 hmac_sha224_base64 hmac_sha224_hex
17 |  |  |  |  | hmac_sha256 hmac_sha256_base64 hmac_sha256_hex
18 |  |  |  |  | hmac_sha384 hmac_sha384_base64 hmac_sha384_hex
19 |  |  |  |  | hmac_sha512 hmac_sha512_base64 hmac_sha512_hex
20 |  |  |  |  | sha1 sha1_base64 sha1_hex
21 |  |  |  |  | sha224 sha224_base64 sha224_hex
22 |  |  |  |  | sha256 sha256_base64 sha256_hex
23 |  |  |  |  | sha384 sha384_base64 sha384_hex
24 |  |  |  |  | sha512 sha512_base64 sha512_hex);
25 |  |  |  |  |
26 |  |  |  |  | # If possible, inherit from Digest::base (which depends on MIME::Base64)
27 |  |  |  |  |
28 | 1 | 900ns |  |  | *addfile = \&Addfile;
29 |  |  |  |  |
30 | 1 | 600ns |  |  | eval {
31 | 1 | 75µs |  |  | require MIME::Base64;
32 | 1 | 81µs |  |  | require Digest::base;
33 | 1 | 13µs |  |  | push(@ISA, 'Digest::base');
34 |  |  |  |  | };
35 | 1 | 200ns |  |  | if ($@) {
36 |  |  |  |  | *hexdigest = \&Hexdigest;
37 |  |  |  |  | *b64digest = \&B64digest;
38 |  |  |  |  | }
39 |  |  |  |  |
40 |  |  |  |  | # The following routines aren't time-critical, so they can be left in Perl
41 |  |  |  |  |
42 |  |  |  |  | # spent 62µs (29+34) within Digest::SHA::new which was called # once (29µs+34µs) by SimpleDB::Class::Item::BEGIN@18 at line 17 of UUID/Tiny.pm sub new {
43 | 8 | 63µs |  |  | my($class, $alg) = @_;
44 |  |  |  |  | $alg =~ s/\D+//g if defined $alg; # spent 2µs making 1 call to Digest::SHA::CORE:subst
45 |  |  |  |  | if (ref($class)) { # instance method
46 |  |  |  |  | unless (defined($alg) && ($alg != $class->algorithm)) {
47 |  |  |  |  | sharewind($$class);
48 |  |  |  |  | return($class);
49 |  |  |  |  | }
50 |  |  |  |  | shaclose($$class) if $$class;
51 |  |  |  |  | $$class = shaopen($alg) || return;
52 |  |  |  |  | return($class);
53 |  |  |  |  | }
54 |  |  |  |  | $alg = 1 unless defined $alg;
55 |  |  |  |  | my $state = shaopen($alg) || return; # spent 31µs making 1 call to Digest::SHA::shaopen
56 |  |  |  |  | my $self = \$state;
57 |  |  |  |  | bless($self, $class);
58 |  |  |  |  | return($self);
59 |  |  |  |  | }
60 |  |  |  |  |
61 |  |  |  |  | sub DESTROY {
62 |  |  |  |  | my $self = shift;
63 |  |  |  |  | shaclose($$self) if $$self;
64 |  |  |  |  | }
65 |  |  |  |  |
66 |  |  |  |  | sub clone {
67 |  |  |  |  | my $self = shift;
68 |  |  |  |  | my $state = shadup($$self) || return;
69 |  |  |  |  | my $copy = \$state;
70 |  |  |  |  | bless($copy, ref($self));
71 |  |  |  |  | return($copy);
72 |  |  |  |  | }
73 |  |  |  |  |
74 | 1 | 1µs |  |  | *reset = \&new;
75 |  |  |  |  |
76 |  |  |  |  | sub add_bits {
77 |  |  |  |  | my($self, $data, $nbits) = @_;
78 |  |  |  |  | unless (defined $nbits) {
79 |  |  |  |  | $nbits = length($data);
80 |  |  |  |  | $data = pack("B*", $data);
81 |  |  |  |  | }
82 |  |  |  |  | shawrite($data, $nbits, $$self);
83 |  |  |  |  | return($self);
84 |  |  |  |  | }
85 |  |  |  |  |
86 |  |  |  |  | sub _bail {
87 |  |  |  |  | my $msg = shift;
88 |  |  |  |  |
89 |  |  |  |  | require Carp;
90 |  |  |  |  | Carp::croak("$msg: $!");
91 |  |  |  |  | }
92 |  |  |  |  |
93 |  |  |  |  | sub _addfile { # this is "addfile" from Digest::base 1.00
94 |  |  |  |  | my ($self, $handle) = @_;
95 |  |  |  |  |
96 |  |  |  |  | my $n;
97 |  |  |  |  | my $buf = "";
98 |  |  |  |  |
99 |  |  |  |  | while (($n = read($handle, $buf, 4096))) {
100 |  |  |  |  | $self->add($buf);
101 |  |  |  |  | }
102 |  |  |  |  | _bail("Read failed") unless defined $n;
103 |  |  |  |  |
104 |  |  |  |  | $self;
105 |  |  |  |  | }
106 |  |  |  |  |
107 |  |  |  |  | sub Addfile {
108 |  |  |  |  | my ($self, $file, $mode) = @_;
109 |  |  |  |  |
110 |  |  |  |  | return(_addfile($self, $file)) unless ref(\$file) eq 'SCALAR';
111 |  |  |  |  |
112 |  |  |  |  | $mode = defined($mode) ? $mode : "";
113 |  |  |  |  | my ($binary, $portable) = map { $_ eq $mode } ("b", "p");
114 |  |  |  |  | my $text = -T $file;
115 |  |  |  |  |
116 |  |  |  |  | local *FH;
117 |  |  |  |  | # protect any leading or trailing whitespace in $file;
118 |  |  |  |  | # otherwise, 2-arg "open" will ignore them
119 |  |  |  |  | $file =~ s#^(\s)#./$1#;
120 |  |  |  |  | open(FH, "< $file\0") or _bail("Open failed");
121 |  |  |  |  | binmode(FH) if $binary || $portable;
122 |  |  |  |  |
123 |  |  |  |  | unless ($portable && $text) {
124 |  |  |  |  | $self->_addfile(*FH);
125 |  |  |  |  | close(FH);
126 |  |  |  |  | return($self);
127 |  |  |  |  | }
128 |  |  |  |  |
129 |  |  |  |  | my ($n1, $n2);
130 |  |  |  |  | my ($buf1, $buf2) = ("", "");
131 |  |  |  |  |
132 |  |  |  |  | while (($n1 = read(FH, $buf1, 4096))) {
133 |  |  |  |  | while (substr($buf1, -1) eq "\015") {
134 |  |  |  |  | $n2 = read(FH, $buf2, 4096);
135 |  |  |  |  | _bail("Read failed") unless defined $n2;
136 |  |  |  |  | last unless $n2;
137 |  |  |  |  | $buf1 .= $buf2;
138 |  |  |  |  | }
139 |  |  |  |  | $buf1 =~ s/\015?\015\012/\012/g; # DOS/Windows
140 |  |  |  |  | $buf1 =~ s/\015/\012/g; # early MacOS
141 |  |  |  |  | $self->add($buf1);
142 |  |  |  |  | }
143 |  |  |  |  | _bail("Read failed") unless defined $n1;
144 |  |  |  |  | close(FH);
145 |  |  |  |  |
146 |  |  |  |  | $self;
147 |  |  |  |  | }
148 |  |  |  |  |
149 |  |  |  |  | sub dump {
150 |  |  |  |  | my $self = shift;
151 |  |  |  |  | my $file = shift || "";
152 |  |  |  |  |
153 |  |  |  |  | shadump($file, $$self) || return;
154 |  |  |  |  | return($self);
155 |  |  |  |  | }
156 |  |  |  |  |
157 |  |  |  |  | sub load {
158 |  |  |  |  | my $class = shift;
159 |  |  |  |  | my $file = shift || "";
160 |  |  |  |  | if (ref($class)) { # instance method
161 |  |  |  |  | shaclose($$class) if $$class;
162 |  |  |  |  | $$class = shaload($file) || return;
163 |  |  |  |  | return($class);
164 |  |  |  |  | }
165 |  |  |  |  | my $state = shaload($file) || return;
166 |  |  |  |  | my $self = \$state;
167 |  |  |  |  | bless($self, $class);
168 |  |  |  |  | return($self);
169 |  |  |  |  | }
170 |  |  |  |  |
171 | 1 | 7µs | 1 | 394µs | Digest::SHA->bootstrap($VERSION); # spent 394µs making 1 call to DynaLoader::bootstrap
172 |  |  |  |  |
173 | 1 | 30µs |  |  | 1;
174 |  |  |  |  | __END__
175 |  |  |  |  |
176 |  |  |  |  | =head1 NAME
177 |  |  |  |  |
178 |  |  |  |  | Digest::SHA - Perl extension for SHA-1/224/256/384/512
179 |  |  |  |  |
180 |  |  |  |  | =head1 SYNOPSIS
181 |  |  |  |  |
182 |  |  |  |  | In programs:
183 |  |  |  |  |
184 |  |  |  |  | # Functional interface
185 |  |  |  |  |
186 |  |  |  |  | use Digest::SHA qw(sha1 sha1_hex sha1_base64 ...);
187 |  |  |  |  |
188 |  |  |  |  | $digest = sha1($data);
189 |  |  |  |  | $digest = sha1_hex($data);
190 |  |  |  |  | $digest = sha1_base64($data);
191 |  |  |  |  |
192 |  |  |  |  | $digest = sha256($data);
193 |  |  |  |  | $digest = sha384_hex($data);
194 |  |  |  |  | $digest = sha512_base64($data);
195 |  |  |  |  |
196 |  |  |  |  | # Object-oriented
197 |  |  |  |  |
198 |  |  |  |  | use Digest::SHA;
199 |  |  |  |  |
200 |  |  |  |  | $sha = Digest::SHA->new($alg);
201 |  |  |  |  |
202 |  |  |  |  | $sha->add($data); # feed data into stream
203 |  |  |  |  |
204 |  |  |  |  | $sha->addfile(*F);
205 |  |  |  |  | $sha->addfile($filename);
206 |  |  |  |  |
207 |  |  |  |  | $sha->add_bits($bits);
208 |  |  |  |  | $sha->add_bits($data, $nbits);
209 |  |  |  |  |
210 |  |  |  |  | $sha_copy = $sha->clone; # if needed, make copy of
211 |  |  |  |  | $sha->dump($file); # current digest state,
212 |  |  |  |  | $sha->load($file); # or save it on disk
213 |  |  |  |  |
214 |  |  |  |  | $digest = $sha->digest; # compute digest
215 |  |  |  |  | $digest = $sha->hexdigest;
216 |  |  |  |  | $digest = $sha->b64digest;
217 |  |  |  |  |
218 |  |  |  |  | From the command line:
219 |  |  |  |  |
220 |  |  |  |  | $ shasum files
221 |  |  |  |  |
222 |  |  |  |  | $ shasum --help
223 |  |  |  |  |
224 |  |  |  |  | =head1 SYNOPSIS (HMAC-SHA)
225 |  |  |  |  |
226 |  |  |  |  | # Functional interface only
227 |  |  |  |  |
228 |  |  |  |  | use Digest::SHA qw(hmac_sha1 hmac_sha1_hex ...);
229 |  |  |  |  |
230 |  |  |  |  | $digest = hmac_sha1($data, $key);
231 |  |  |  |  | $digest = hmac_sha224_hex($data, $key);
232 |  |  |  |  | $digest = hmac_sha256_base64($data, $key);
233 |  |  |  |  |
234 |  |  |  |  | =head1 ABSTRACT
235 |  |  |  |  |
236 |  |  |  |  | Digest::SHA is a complete implementation of the NIST Secure Hash
237 |  |  |  |  | Standard. It gives Perl programmers a convenient way to calculate
238 |  |  |  |  | SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512 message digests.
239 |  |  |  |  | The module can handle all types of input, including partial-byte
240 |  |  |  |  | data.
241 |  |  |  |  |
242 |  |  |  |  | =head1 DESCRIPTION
243 |  |  |  |  |
244 |  |  |  |  | Digest::SHA is written in C for speed. If your platform lacks a
245 |  |  |  |  | C compiler, you can install the functionally equivalent (but much
246 |  |  |  |  | slower) L<Digest::SHA::PurePerl> module.
247 |  |  |  |  |
248 |  |  |  |  | The programming interface is easy to use: it's the same one found
249 |  |  |  |  | in CPAN's L<Digest> module. So, if your applications currently
250 |  |  |  |  | use L<Digest::MD5> and you'd prefer the stronger security of SHA,
251 |  |  |  |  | it's a simple matter to convert them.
252 |  |  |  |  |
253 |  |  |  |  | The interface provides two ways to calculate digests: all-at-once,
254 |  |  |  |  | or in stages. To illustrate, the following short program computes
255 |  |  |  |  | the SHA-256 digest of "hello world" using each approach:
256 |  |  |  |  |
257 |  |  |  |  | use Digest::SHA qw(sha256_hex);
258 |  |  |  |  |
259 |  |  |  |  | $data = "hello world";
260 |  |  |  |  | @frags = split(//, $data);
261 |  |  |  |  |
262 |  |  |  |  | # all-at-once (Functional style)
263 |  |  |  |  | $digest1 = sha256_hex($data);
264 |  |  |  |  |
265 |  |  |  |  | # in-stages (OOP style)
266 |  |  |  |  | $state = Digest::SHA->new(256);
267 |  |  |  |  | for (@frags) { $state->add($_) }
268 |  |  |  |  | $digest2 = $state->hexdigest;
269 |  |  |  |  |
270 |  |  |  |  | print $digest1 eq $digest2 ?
271 |  |  |  |  | "whew!\n" : "oops!\n";
272 |  |  |  |  |
273 |  |  |  |  | To calculate the digest of an n-bit message where I<n> is not a
274 |  |  |  |  | multiple of 8, use the I<add_bits()> method. For example, consider
275 |  |  |  |  | the 446-bit message consisting of the bit-string "110" repeated
276 |  |  |  |  | 148 times, followed by "11". Here's how to display its SHA-1
277 |  |  |  |  | digest:
278 |  |  |  |  |
279 |  |  |  |  | use Digest::SHA;
280 |  |  |  |  | $bits = "110" x 148 . "11";
281 |  |  |  |  | $sha = Digest::SHA->new(1)->add_bits($bits);
282 |  |  |  |  | print $sha->hexdigest, "\n";
283 |  |  |  |  |
284 |  |  |  |  | Note that for larger bit-strings, it's more efficient to use the
285 |  |  |  |  | two-argument version I<add_bits($data, $nbits)>, where I<$data> is
286 |  |  |  |  | in the customary packed binary format used for Perl strings.
287 |  |  |  |  |
288 |  |  |  |  | The module also lets you save intermediate SHA states to disk, or
289 |  |  |  |  | display them on standard output. The I<dump()> method generates
290 |  |  |  |  | portable, human-readable text describing the current state of
291 |  |  |  |  | computation. You can subsequently retrieve the file with I<load()>
292 |  |  |  |  | to resume where the calculation left off.
293 |  |  |  |  |
294 |  |  |  |  | To see what a state description looks like, just run the following:
295 |  |  |  |  |
296 |  |  |  |  | use Digest::SHA;
297 |  |  |  |  | Digest::SHA->new->add("Shaw" x 1962)->dump;
298 |  |  |  |  |
299 |  |  |  |  | As an added convenience, the Digest::SHA module offers routines to
300 |  |  |  |  | calculate keyed hashes using the HMAC-SHA-1/224/256/384/512
301 |  |  |  |  | algorithms. These services exist in functional form only, and
302 |  |  |  |  | mimic the style and behavior of the I<sha()>, I<sha_hex()>, and
303 |  |  |  |  | I<sha_base64()> functions.
304 |  |  |  |  |
305 |  |  |  |  | # Test vector from draft-ietf-ipsec-ciph-sha-256-01.txt
306 |  |  |  |  |
307 |  |  |  |  | use Digest::SHA qw(hmac_sha256_hex);
308 |  |  |  |  | print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\n";
309 |  |  |  |  |
310 |  |  |  |  | =head1 NIST STATEMENT ON SHA-1
311 |  |  |  |  |
312 |  |  |  |  | I<NIST was recently informed that researchers had discovered a way
313 |  |  |  |  | to "break" the current Federal Information Processing Standard SHA-1
314 |  |  |  |  | algorithm, which has been in effect since 1994. The researchers
315 |  |  |  |  | have not yet published their complete results, so NIST has not
316 |  |  |  |  | confirmed these findings. However, the researchers are a reputable
317 |  |  |  |  | research team with expertise in this area.>
318 |  |  |  |  |
319 |  |  |  |  | I<Due to advances in computing power, NIST already planned to phase
320 |  |  |  |  | out SHA-1 in favor of the larger and stronger hash functions (SHA-224,
321 |  |  |  |  | SHA-256, SHA-384 and SHA-512) by 2010. New developments should use
322 |  |  |  |  | the larger and stronger hash functions.>
323 |  |  |  |  |
324 |  |  |  |  | ref. L<http://www.csrc.nist.gov/pki/HashWorkshop/NIST%20Statement/Burr_Mar2005.html>
325 |  |  |  |  |
326 |  |  |  |  | =head1 PADDING OF BASE64 DIGESTS
327 |  |  |  |  |
328 |  |  |  |  | By convention, CPAN Digest modules do B<not> pad their Base64 output.
329 |  |  |  |  | Problems can occur when feeding such digests to other software that
330 |  |  |  |  | expects properly padded Base64 encodings.
331 |  |  |  |  |
332 |  |  |  |  | For the time being, any necessary padding must be done by the user.
333 |  |  |  |  | Fortunately, this is a simple operation: if the length of a Base64-encoded
334 |  |  |  |  | digest isn't a multiple of 4, simply append "=" characters to the end
335 |  |  |  |  | of the digest until it is:
336 |  |  |  |  |
337 |  |  |  |  | while (length($b64_digest) % 4) {
338 |  |  |  |  | $b64_digest .= '=';
339 |  |  |  |  | }
340 |  |  |  |  |
341 |  |  |  |  | To illustrate, I<sha256_base64("abc")> is computed to be
342 |  |  |  |  |
343 |  |  |  |  | ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0
344 |  |  |  |  |
345 |  |  |  |  | which has a length of 43. So, the properly padded version is
346 |  |  |  |  |
347 |  |  |  |  | ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
348 |  |  |  |  |
349 |  |  |  |  | =head1 EXPORT
350 |  |  |  |  |
351 |  |  |  |  | None by default.
352 |  |  |  |  |
353 |  |  |  |  | =head1 EXPORTABLE FUNCTIONS
354 |  |  |  |  |
355 |  |  |  |  | Provided your C compiler supports a 64-bit type (e.g. the I<long
356 |  |  |  |  | long> of C99, or I<__int64> used by Microsoft C/C++), all of these
357 |  |  |  |  | functions will be available for use. Otherwise, you won't be able
358 |  |  |  |  | to perform the SHA-384 and SHA-512 transforms, both of which require
359 |  |  |  |  | 64-bit operations.
360 |  |  |  |  |
361 |  |  |  |  | I<Functional style>
362 |  |  |  |  |
363 |  |  |  |  | =over 4
364 |  |  |  |  |
365 |  |  |  |  | =item B<sha1($data, ...)>
366 |  |  |  |  |
367 |  |  |  |  | =item B<sha224($data, ...)>
368 |  |  |  |  |
369 |  |  |  |  | =item B<sha256($data, ...)>
370 |  |  |  |  |
371 |  |  |  |  | =item B<sha384($data, ...)>
372 |  |  |  |  |
373 |  |  |  |  | =item B<sha512($data, ...)>
374 |  |  |  |  |
375 |  |  |  |  | Logically joins the arguments into a single string, and returns
376 |  |  |  |  | its SHA-1/224/256/384/512 digest encoded as a binary string.
377 |  |  |  |  |
378 |  |  |  |  | =item B<sha1_hex($data, ...)>
379 |  |  |  |  |
380 |  |  |  |  | =item B<sha224_hex($data, ...)>
381 |  |  |  |  |
382 |  |  |  |  | =item B<sha256_hex($data, ...)>
383 |  |  |  |  |
384 |  |  |  |  | =item B<sha384_hex($data, ...)>
385 |  |  |  |  |
386 |  |  |  |  | =item B<sha512_hex($data, ...)>
387 |  |  |  |  |
388 |  |  |  |  | Logically joins the arguments into a single string, and returns
389 |  |  |  |  | its SHA-1/224/256/384/512 digest encoded as a hexadecimal string.
390 |  |  |  |  |
391 |  |  |  |  | =item B<sha1_base64($data, ...)>
392 |  |  |  |  |
393 |  |  |  |  | =item B<sha224_base64($data, ...)>
394 |  |  |  |  |
395 |  |  |  |  | =item B<sha256_base64($data, ...)>
396 |  |  |  |  |
397 |  |  |  |  | =item B<sha384_base64($data, ...)>
398 |  |  |  |  |
399 |  |  |  |  | =item B<sha512_base64($data, ...)>
400 |  |  |  |  |
401 |  |  |  |  | Logically joins the arguments into a single string, and returns
402 |  |  |  |  | its SHA-1/224/256/384/512 digest encoded as a Base64 string.
403 |  |  |  |  |
404 |  |  |  |  | It's important to note that the resulting string does B<not> contain
405 |  |  |  |  | the padding characters typical of Base64 encodings. This omission is
406 |  |  |  |  | deliberate, and is done to maintain compatibility with the family of
407 |  |  |  |  | CPAN Digest modules. See L</"PADDING OF BASE64 DIGESTS"> for details.
408 |  |  |  |  |
409 |  |  |  |  | =back
410 |  |  |  |  |
411 |  |  |  |  | I<OOP style>
412 |  |  |  |  |
413 |  |  |  |  | =over 4
414 |  |  |  |  |
415 |  |  |  |  | =item B<new($alg)>
416 |  |  |  |  |
417 |  |  |  |  | Returns a new Digest::SHA object. Allowed values for I<$alg> are
418 |  |  |  |  | 1, 224, 256, 384, or 512. It's also possible to use common string
419 |  |  |  |  | representations of the algorithm (e.g. "sha256", "SHA-384"). If
420 |  |  |  |  | the argument is missing, SHA-1 will be used by default.
421 |  |  |  |  |
422 |  |  |  |  | Invoking I<new> as an instance method will not create a new object;
423 |  |  |  |  | instead, it will simply reset the object to the initial state
424 |  |  |  |  | associated with I<$alg>. If the argument is missing, the object
425 |  |  |  |  | will continue using the same algorithm that was selected at creation.
426 |  |  |  |  |
427 |  |  |  |  | =item B<reset($alg)>
428 |  |  |  |  |
429 |  |  |  |  | This method has exactly the same effect as I<new($alg)>. In fact,
430 |  |  |  |  | I<reset> is just an alias for I<new>.
431 |  |  |  |  |
432 |  |  |  |  | =item B<hashsize>
433 |  |  |  |  |
434 |  |  |  |  | Returns the number of digest bits for this object. The values are
435 |  |  |  |  | 160, 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384,
436 |  |  |  |  | and SHA-512, respectively.
437 |  |  |  |  |
438 |  |  |  |  | =item B<algorithm>
439 |  |  |  |  |
440 |  |  |  |  | Returns the digest algorithm for this object. The values are 1,
441 |  |  |  |  | 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384, and
442 |  |  |  |  | SHA-512, respectively.
443 |  |  |  |  |
444 |  |  |  |  | =item B<clone>
445 |  |  |  |  |
446 |  |  |  |  | Returns a duplicate copy of the object.
447 |  |  |  |  |
448 |  |  |  |  | =item B<add($data, ...)>
449 |  |  |  |  |
450 |  |  |  |  | Logically joins the arguments into a single string, and uses it to
451 |  |  |  |  | update the current digest state. In other words, the following
452 |  |  |  |  | statements have the same effect:
453 |  |  |  |  |
454 |  |  |  |  | $sha->add("a"); $sha->add("b"); $sha->add("c");
455 |  |  |  |  | $sha->add("a")->add("b")->add("c");
456 |  |  |  |  | $sha->add("a", "b", "c");
457 |  |  |  |  | $sha->add("abc");
458 |  |  |  |  |
459 |  |  |  |  | The return value is the updated object itself.
460 |  |  |  |  |
461 |  |  |  |  | =item B<add_bits($data, $nbits)>
462 |  |  |  |  |
463 |  |  |  |  | =item B<add_bits($bits)>
464 |  |  |  |  |
465 |  |  |  |  | Updates the current digest state by appending bits to it. The
466 |  |  |  |  | return value is the updated object itself.
467 |  |  |  |  |
468 |  |  |  |  | The first form causes the most-significant I<$nbits> of I<$data>
469 |  |  |  |  | to be appended to the stream. The I<$data> argument is in the
470 |  |  |  |  | customary binary format used for Perl strings.
471 |  |  |  |  |
472 |  |  |  |  | The second form takes an ASCII string of "0" and "1" characters as
473 |  |  |  |  | its argument. It's equivalent to
474 |  |  |  |  |
475 |  |  |  |  | $sha->add_bits(pack("B*", $bits), length($bits));
476 |  |  |  |  |
477 |  |  |  |  | So, the following two statements do the same thing:
478 |  |  |  |  |
479 |  |  |  |  | $sha->add_bits("111100001010");
480 |  |  |  |  | $sha->add_bits("\xF0\xA0", 12);
481 |  |  |  |  |
482 |  |  |  |  | =item B<addfile(*FILE)>
483 |  |  |  |  |
484 |  |  |  |  | Reads from I<FILE> until EOF, and appends that data to the current
485 |  |  |  |  | state. The return value is the updated object itself.
486 |  |  |  |  |
487 |  |  |  |  | =item B<addfile($filename [, $mode])>
488 |  |  |  |  |
489 |  |  |  |  | Reads the contents of I<$filename>, and appends that data to the current
490 |  |  |  |  | state. The return value is the updated object itself.
491 |  |  |  |  |
492 |  |  |  |  | By default, I<$filename> is simply opened and read; no special modes
493 |  |  |  |  | or I/O disciplines are used. To change this, set the optional I<$mode>
494 |  |  |  |  | argument to one of the following values:
495 |  |  |  |  |
496 |  |  |  |  | "b" read file in binary mode
497 |  |  |  |  |
498 |  |  |  |  | "p" use portable mode
499 |  |  |  |  |
500 |  |  |  |  | The "p" mode is handy since it ensures that the digest value of
501 |  |  |  |  | I<$filename> will be the same when computed on different operating
502 |  |  |  |  | systems. It accomplishes this by internally translating all newlines in
503 |  |  |  |  | text files to UNIX format before calculating the digest. Binary files
504 |  |  |  |  | are read in raw mode with no translation whatsoever.
505 |  |  |  |  |
506 |  |  |  |  | For a fuller discussion of newline formats, refer to CPAN module
507 |  |  |  |  | L<File::LocalizeNewlines>. Its "universal line separator" regex forms
508 |  |  |  |  | the basis of I<addfile>'s portable mode processing.
509 |  |  |  |  |
510 |  |  |  |  | =item B<dump($filename)>
511 |  |  |  |  |
512 |  |  |  |  | Provides persistent storage of intermediate SHA states by writing
513 |  |  |  |  | a portable, human-readable representation of the current state to
514 |  |  |  |  | I<$filename>. If the argument is missing, or equal to the empty
515 |  |  |  |  | string, the state information will be written to STDOUT.
516 |  |  |  |  |
517 |  |  |  |  | =item B<load($filename)>
518 |  |  |  |  |
519 |  |  |  |  | Returns a Digest::SHA object representing the intermediate SHA
520 |  |  |  |  | state that was previously dumped to I<$filename>. If called as a
521 |  |  |  |  | class method, a new object is created; if called as an instance
522 |  |  |  |  | method, the object is reset to the state contained in I<$filename>.
523 |  |  |  |  | If the argument is missing, or equal to the empty string, the state
524 |  |  |  |  | information will be read from STDIN.
525 |  |  |  |  |
526 |  |  |  |  | =item B<digest>
527 |  |  |  |  |
528 |  |  |  |  | Returns the digest encoded as a binary string.
529 |  |  |  |  |
530 |  |  |  |  | Note that the I<digest> method is a read-once operation. Once it
531 |  |  |  |  | has been performed, the Digest::SHA object is automatically reset
532 |  |  |  |  | in preparation for calculating another digest value. Call
533 |  |  |  |  | I<$sha-E<gt>clone-E<gt>digest> if it's necessary to preserve the
534 |  |  |  |  | original digest state.
535 |  |  |  |  |
536 |  |  |  |  | =item B<hexdigest>
537 |  |  |  |  |
538 |  |  |  |  | Returns the digest encoded as a hexadecimal string.
539 |  |  |  |  |
540 |  |  |  |  | Like I<digest>, this method is a read-once operation. Call
541 |  |  |  |  | I<$sha-E<gt>clone-E<gt>hexdigest> if it's necessary to preserve
542 |  |  |  |  | the original digest state.
543 |  |  |  |  |
544 |  |  |  |  | This method is inherited if L<Digest::base> is installed on your
545 |  |  |  |  | system. Otherwise, a functionally equivalent substitute is used.
546 |  |  |  |  |
547 |  |  |  |  | =item B<b64digest>
548 |  |  |  |  |
549 |  |  |  |  | Returns the digest encoded as a Base64 string.
550 |  |  |  |  |
551 |  |  |  |  | Like I<digest>, this method is a read-once operation. Call
552 |  |  |  |  | I<$sha-E<gt>clone-E<gt>b64digest> if it's necessary to preserve
553 |  |  |  |  | the original digest state.
554 |  |  |  |  |
555 |  |  |  |  | This method is inherited if L<Digest::base> is installed on your
556 |  |  |  |  | system. Otherwise, a functionally equivalent substitute is used.
557 |  |  |  |  |
558 |  |  |  |  | It's important to note that the resulting string does B<not> contain
559 |  |  |  |  | the padding characters typical of Base64 encodings. This omission is
560 |  |  |  |  | deliberate, and is done to maintain compatibility with the family of
561 |  |  |  |  | CPAN Digest modules. See L</"PADDING OF BASE64 DIGESTS"> for details.
562 |  |  |  |  |
563 |  |  |  |  | =back
564 |  |  |  |  |
565 |  |  |  |  | I<HMAC-SHA-1/224/256/384/512>
566 |  |  |  |  |
567 |  |  |  |  | =over 4
568 |  |  |  |  |
569 |  |  |  |  | =item B<hmac_sha1($data, $key)>
570 |  |  |  |  |
571 |  |  |  |  | =item B<hmac_sha224($data, $key)>
572 |  |  |  |  |
573 |  |  |  |  | =item B<hmac_sha256($data, $key)>
574 |  |  |  |  |
575 |  |  |  |  | =item B<hmac_sha384($data, $key)>
576 |  |  |  |  |
577 |  |  |  |  | =item B<hmac_sha512($data, $key)>
578 |  |  |  |  |
579 |  |  |  |  | Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
580 |  |  |  |  | with the result encoded as a binary string. Multiple I<$data>
581 |  |  |  |  | arguments are allowed, provided that I<$key> is the last argument
582 |  |  |  |  | in the list.
583 |  |  |  |  |
584 |  |  |  |  | =item B<hmac_sha1_hex($data, $key)>
585 |  |  |  |  |
586 |  |  |  |  | =item B<hmac_sha224_hex($data, $key)>
587 |  |  |  |  |
588 |  |  |  |  | =item B<hmac_sha256_hex($data, $key)>
589 |  |  |  |  |
590 |  |  |  |  | =item B<hmac_sha384_hex($data, $key)>
591 |  |  |  |  |
592 |  |  |  |  | =item B<hmac_sha512_hex($data, $key)>
593 |  |  |  |  |
594 |  |  |  |  | Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
595 |  |  |  |  | with the result encoded as a hexadecimal string. Multiple I<$data>
596 |  |  |  |  | arguments are allowed, provided that I<$key> is the last argument
597 |  |  |  |  | in the list.
598 |  |  |  |  |
599 |  |  |  |  | =item B<hmac_sha1_base64($data, $key)>
600 |  |  |  |  |
601 |  |  |  |  | =item B<hmac_sha224_base64($data, $key)>
602 |  |  |  |  |
603 |  |  |  |  | =item B<hmac_sha256_base64($data, $key)>
604 |  |  |  |  |
605 |  |  |  |  | =item B<hmac_sha384_base64($data, $key)>
606 |  |  |  |  |
607 |  |  |  |  | =item B<hmac_sha512_base64($data, $key)>
608 |  |  |  |  |
609 |  |  |  |  | Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>,
610 |  |  |  |  | with the result encoded as a Base64 string. Multiple I<$data>
611 |  |  |  |  | arguments are allowed, provided that I<$key> is the last argument
612 |  |  |  |  | in the list.
613 |  |  |  |  |
614 |  |  |  |  | It's important to note that the resulting string does B<not> contain
615 |  |  |  |  | the padding characters typical of Base64 encodings. This omission is
616 |  |  |  |  | deliberate, and is done to maintain compatibility with the family of
617 |  |  |  |  | CPAN Digest modules. See L</"PADDING OF BASE64 DIGESTS"> for details.
618 |  |  |  |  |
619 |  |  |  |  | =back
620 |  |  |  |  |
621 |  |  |  |  | =head1 SEE ALSO
622 |  |  |  |  |
623 |  |  |  |  | L<Digest>, L<Digest::SHA::PurePerl>
624 |  |  |  |  |
625 |  |  |  |  | The Secure Hash Standard (FIPS PUB 180-2) can be found at:
626 |  |  |  |  |
627 |  |  |  |  | L<http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf>
628 |  |  |  |  |
629 |  |  |  |  | The Keyed-Hash Message Authentication Code (HMAC):
630 |  |  |  |  |
631 |  |  |  |  | L<http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf>
632 |  |  |  |  |
633 |  |  |  |  | =head1 AUTHOR
634 |  |  |  |  |
635 |  |  |  |  | Mark Shelor <mshelor@cpan.org>
636 |  |  |  |  |
637 |  |  |  |  | =head1 ACKNOWLEDGMENTS
638 |  |  |  |  |
639 |  |  |  |  | The author is particularly grateful to
640 |  |  |  |  |
641 |  |  |  |  | Gisle Aas
642 |  |  |  |  | Chris Carey
643 |  |  |  |  | Alexandr Ciornii
644 |  |  |  |  | Jim Doble
645 |  |  |  |  | Julius Duque
646 |  |  |  |  | Jeffrey Friedl
647 |  |  |  |  | Robert Gilmour
648 |  |  |  |  | Brian Gladman
649 |  |  |  |  | Adam Kennedy
650 |  |  |  |  | Andy Lester
651 |  |  |  |  | Alex Muntada
652 |  |  |  |  | Steve Peters
653 |  |  |  |  | Chris Skiscim
654 |  |  |  |  | Martin Thurn
655 |  |  |  |  | Gunnar Wolf
656 |  |  |  |  | Adam Woodbury
657 |  |  |  |  |
658 |  |  |  |  | for their valuable comments and suggestions.
659 |  |  |  |  |
660 |  |  |  |  | =head1 COPYRIGHT AND LICENSE
661 |  |  |  |  |
662 |  |  |  |  | Copyright (C) 2003-2008 Mark Shelor
663 |  |  |  |  |
664 |  |  |  |  | This library is free software; you can redistribute it and/or modify
665 |  |  |  |  | it under the same terms as Perl itself.
666 |  |  |  |  |
667 |  |  |  |  | L<perlartistic>
668 |  |  |  |  |
669 |  |  |  |  | =cut
|  |  |  |  | # spent 2µs within Digest::SHA::CORE:subst which was called # once (2µs+0s) by Digest::SHA::new at line 44 of Digest/SHA.pm sub Digest::SHA::CORE:subst; # xsub
|  |  |  |  | # spent 86µs within Digest::SHA::bootstrap which was called # once (86µs+0s) by DynaLoader::bootstrap at line 227 of DynaLoader.pm sub Digest::SHA::bootstrap; # xsub
|  |  |  |  | # spent 773µs within Digest::SHA::hmac_sha256_base64 which was called 41 times, avg 19µs/call: # 41 times (773µs+0s) by SimpleDB::Client::construct_request at line 178 of SimpleDB/Client.pm, avg 19µs/call sub Digest::SHA::hmac_sha256_base64; # xsub
|  |  |  |  | # spent 31µs within Digest::SHA::shaopen which was called # once (31µs+0s) by Digest::SHA::new at line 55 of Digest/SHA.pm sub Digest::SHA::shaopen; # xsub