1Digest::SHA(3pm) Perl Programmers Reference Guide Digest::SHA(3pm)
2
6 Digest::SHA - Perl extension for SHA-1/224/256/384/512
7
9 In programs:
10 # Functional interface
12 use Digest::SHA qw(sha1 sha1_hex sha1_base64 ...);
14 $digest = sha1($data);
16 $digest = sha1_hex($data);
17 $digest = sha1_base64($data);
18 $digest = sha256($data);
20 $digest = sha384_hex($data);
21 $digest = sha512_base64($data);
22 # Object-oriented
24 use Digest::SHA;
26 $sha = Digest::SHA->new($alg);
28 $sha->add($data); # feed data into stream
30 $sha->addfile(*F);
32 $sha->addfile($filename);
33 $sha->add_bits($bits);
35 $sha->add_bits($data, $nbits);
36 $sha_copy = $sha->clone; # if needed, make copy of
38 $sha->dump($file); # current digest state,
39 $sha->load($file); # or save it on disk
40 $digest = $sha->digest; # compute digest
42 $digest = $sha->hexdigest;
43 $digest = $sha->b64digest;
44 From the command line:
46 $ shasum files
48 $ shasum --help
50
52 # Functional interface only
53 use Digest::SHA qw(hmac_sha1 hmac_sha1_hex ...);
55 $digest = hmac_sha1($data, $key);
57 $digest = hmac_sha224_hex($data, $key);
58 $digest = hmac_sha256_base64($data, $key);
59
61 Digest::SHA is a complete implementation of the NIST Secure Hash
62 Standard. It gives Perl programmers a convenient way to calculate
63 SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512 message digests. The
64 module can handle all types of input, including partial-byte data.
65
67 Digest::SHA is written in C for speed. If your platform lacks a C
68 compiler, you can install the functionally equivalent (but much slower)
69 Digest::SHA::PurePerl module.
70 The programming interface is easy to use: it's the same one found in
72 CPAN's Digest module. So, if your applications currently use
73 Digest::MD5 and you'd prefer the stronger security of SHA, it's a
74 simple matter to convert them.
75 The interface provides two ways to calculate digests: all-at-once, or
77 in stages. To illustrate, the following short program computes the
78 SHA-256 digest of "hello world" using each approach:
79 use Digest::SHA qw(sha256_hex);
81 $data = "hello world";
83 @frags = split(//, $data);
84 # all-at-once (Functional style)
86 $digest1 = sha256_hex($data);
87 # in-stages (OOP style)
89 $state = Digest::SHA->new(256);
90 for (@frags) { $state->add($_) }
91 $digest2 = $state->hexdigest;
92 print $digest1 eq $digest2 ?
94 "whew!\n" : "oops!\n";
95 To calculate the digest of an n-bit message where n is not a multiple
97 of 8, use the add_bits() method. For example, consider the 446-bit
98 message consisting of the bit-string "110" repeated 148 times, followed
99 by "11". Here's how to display its SHA-1 digest:
100 use Digest::SHA;
102 $bits = "110" x 148 . "11";
103 $sha = Digest::SHA->new(1)->add_bits($bits);
104 print $sha->hexdigest, "\n";
105 Note that for larger bit-strings, it's more efficient to use the two-
107 argument version add_bits($data, $nbits), where $data is in the
108 customary packed binary format used for Perl strings.
109 The module also lets you save intermediate SHA states to disk, or
111 display them on standard output. The dump() method generates portable,
112 human-readable text describing the current state of computation. You
113 can subsequently retrieve the file with load() to resume where the
114 calculation left off.
115 To see what a state description looks like, just run the following:
117 use Digest::SHA;
119 Digest::SHA->new->add("Shaw" x 1962)->dump;
120 As an added convenience, the Digest::SHA module offers routines to
122 calculate keyed hashes using the HMAC-SHA-1/224/256/384/512 algorithms.
123 These services exist in functional form only, and mimic the style and
124 behavior of the sha(), sha_hex(), and sha_base64() functions.
125 # Test vector from draft-ietf-ipsec-ciph-sha-256-01.txt
127 use Digest::SHA qw(hmac_sha256_hex);
129 print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\n";
130
132 NIST was recently informed that researchers had discovered a way to
133 "break" the current Federal Information Processing Standard SHA-1
134 algorithm, which has been in effect since 1994. The researchers have
135 not yet published their complete results, so NIST has not confirmed
136 these findings. However, the researchers are a reputable research team
137 with expertise in this area.
138 Due to advances in computing power, NIST already planned to phase out
140 SHA-1 in favor of the larger and stronger hash functions (SHA-224,
141 SHA-256, SHA-384 and SHA-512) by 2010. New developments should use the
142 larger and stronger hash functions.
143 ref.
145 <http://www.csrc.nist.gov/pki/HashWorkshop/NIST%20Statement/Burr_Mar2005.html>
146
148 By convention, CPAN Digest modules do not pad their Base64 output.
149 Problems can occur when feeding such digests to other software that
150 expects properly padded Base64 encodings.
151 For the time being, any necessary padding must be done by the user.
153 Fortunately, this is a simple operation: if the length of a
154 Base64-encoded digest isn't a multiple of 4, simply append "="
155 characters to the end of the digest until it is:
156 while (length($b64_digest) % 4) {
158 $b64_digest .= '=';
159 }
160 To illustrate, sha256_base64("abc") is computed to be
162 ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0
164 which has a length of 43. So, the properly padded version is
166 ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
168
170 None by default.
171
173 Provided your C compiler supports a 64-bit type (e.g. the long long of
174 C99, or __int64 used by Microsoft C/C++), all of these functions will
175 be available for use. Otherwise, you won't be able to perform the
176 SHA-384 and SHA-512 transforms, both of which require 64-bit
177 operations.
178 Functional style
180 sha1($data, ...)
182 sha224($data, ...)
183 sha256($data, ...)
184 sha384($data, ...)
185 sha512($data, ...)
186 Logically joins the arguments into a single string, and returns its
187 SHA-1/224/256/384/512 digest encoded as a binary string.
188 sha1_hex($data, ...)
190 sha224_hex($data, ...)
191 sha256_hex($data, ...)
192 sha384_hex($data, ...)
193 sha512_hex($data, ...)
194 Logically joins the arguments into a single string, and returns its
195 SHA-1/224/256/384/512 digest encoded as a hexadecimal string.
196 sha1_base64($data, ...)
198 sha224_base64($data, ...)
199 sha256_base64($data, ...)
200 sha384_base64($data, ...)
201 sha512_base64($data, ...)
202 Logically joins the arguments into a single string, and returns its
203 SHA-1/224/256/384/512 digest encoded as a Base64 string.
204 It's important to note that the resulting string does not contain
206 the padding characters typical of Base64 encodings. This omission
207 is deliberate, and is done to maintain compatibility with the
208 family of CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for
209 details.
210 OOP style
212 new($alg)
214 Returns a new Digest::SHA object. Allowed values for $alg are 1,
215 224, 256, 384, or 512. It's also possible to use common string
216 representations of the algorithm (e.g. "sha256", "SHA-384"). If
217 the argument is missing, SHA-1 will be used by default.
218 Invoking new as an instance method will not create a new object;
220 instead, it will simply reset the object to the initial state
221 associated with $alg. If the argument is missing, the object will
222 continue using the same algorithm that was selected at creation.
223 reset($alg)
225 This method has exactly the same effect as new($alg). In fact,
226 reset is just an alias for new.
227 hashsize
229 Returns the number of digest bits for this object. The values are
230 160, 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384,
231 and SHA-512, respectively.
232 algorithm
234 Returns the digest algorithm for this object. The values are 1,
235 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384, and
236 SHA-512, respectively.
237 clone
239 Returns a duplicate copy of the object.
240 add($data, ...)
242 Logically joins the arguments into a single string, and uses it to
243 update the current digest state. In other words, the following
244 statements have the same effect:
245 $sha->add("a"); $sha->add("b"); $sha->add("c");
247 $sha->add("a")->add("b")->add("c");
248 $sha->add("a", "b", "c");
249 $sha->add("abc");
250 The return value is the updated object itself.
252 add_bits($data, $nbits)
254 add_bits($bits)
255 Updates the current digest state by appending bits to it. The
256 return value is the updated object itself.
257 The first form causes the most-significant $nbits of $data to be
259 appended to the stream. The $data argument is in the customary
260 binary format used for Perl strings.
261 The second form takes an ASCII string of "0" and "1" characters as
263 its argument. It's equivalent to
264 $sha->add_bits(pack("B*", $bits), length($bits));
266 So, the following two statements do the same thing:
268 $sha->add_bits("111100001010");
270 $sha->add_bits("\xF0\xA0", 12);
271 addfile(*FILE)
273 Reads from FILE until EOF, and appends that data to the current
274 state. The return value is the updated object itself.
275 addfile($filename [, $mode])
277 Reads the contents of $filename, and appends that data to the
278 current state. The return value is the updated object itself.
279 By default, $filename is simply opened and read; no special modes
281 or I/O disciplines are used. To change this, set the optional
282 $mode argument to one of the following values:
283 "b" read file in binary mode
285 "p" use portable mode
287 The "p" mode is handy since it ensures that the digest value of
289 $filename will be the same when computed on different operating
290 systems. It accomplishes this by internally translating all
291 newlines in text files to UNIX format before calculating the
292 digest. Binary files are read in raw mode with no translation
293 whatsoever.
294 For a fuller discussion of newline formats, refer to CPAN module
296 File::LocalizeNewlines. Its "universal line separator" regex forms
297 the basis of addfile's portable mode processing.
298 dump($filename)
300 Provides persistent storage of intermediate SHA states by writing a
301 portable, human-readable representation of the current state to
302 $filename. If the argument is missing, or equal to the empty
303 string, the state information will be written to STDOUT.
304 load($filename)
306 Returns a Digest::SHA object representing the intermediate SHA
307 state that was previously dumped to $filename. If called as a
308 class method, a new object is created; if called as an instance
309 method, the object is reset to the state contained in $filename.
310 If the argument is missing, or equal to the empty string, the state
311 information will be read from STDIN.
312 digest
314 Returns the digest encoded as a binary string.
315 Note that the digest method is a read-once operation. Once it has
317 been performed, the Digest::SHA object is automatically reset in
318 preparation for calculating another digest value. Call
319 $sha->clone->digest if it's necessary to preserve the original
320 digest state.
321 hexdigest
323 Returns the digest encoded as a hexadecimal string.
324 Like digest, this method is a read-once operation. Call
326 $sha->clone->hexdigest if it's necessary to preserve the original
327 digest state.
328 This method is inherited if Digest::base is installed on your
330 system. Otherwise, a functionally equivalent substitute is used.
331 b64digest
333 Returns the digest encoded as a Base64 string.
334 Like digest, this method is a read-once operation. Call
336 $sha->clone->b64digest if it's necessary to preserve the original
337 digest state.
338 This method is inherited if Digest::base is installed on your
340 system. Otherwise, a functionally equivalent substitute is used.
341 It's important to note that the resulting string does not contain
343 the padding characters typical of Base64 encodings. This omission
344 is deliberate, and is done to maintain compatibility with the
345 family of CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for
346 details.
347 HMAC-SHA-1/224/256/384/512
349 hmac_sha1($data, $key)
351 hmac_sha224($data, $key)
352 hmac_sha256($data, $key)
353 hmac_sha384($data, $key)
354 hmac_sha512($data, $key)
355 Returns the HMAC-SHA-1/224/256/384/512 digest of $data/$key, with
356 the result encoded as a binary string. Multiple $data arguments
357 are allowed, provided that $key is the last argument in the list.
358 hmac_sha1_hex($data, $key)
360 hmac_sha224_hex($data, $key)
361 hmac_sha256_hex($data, $key)
362 hmac_sha384_hex($data, $key)
363 hmac_sha512_hex($data, $key)
364 Returns the HMAC-SHA-1/224/256/384/512 digest of $data/$key, with
365 the result encoded as a hexadecimal string. Multiple $data
366 arguments are allowed, provided that $key is the last argument in
367 the list.
368 hmac_sha1_base64($data, $key)
370 hmac_sha224_base64($data, $key)
371 hmac_sha256_base64($data, $key)
372 hmac_sha384_base64($data, $key)
373 hmac_sha512_base64($data, $key)
374 Returns the HMAC-SHA-1/224/256/384/512 digest of $data/$key, with
375 the result encoded as a Base64 string. Multiple $data arguments
376 are allowed, provided that $key is the last argument in the list.
377 It's important to note that the resulting string does not contain
379 the padding characters typical of Base64 encodings. This omission
380 is deliberate, and is done to maintain compatibility with the
381 family of CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for
382 details.
383
385 Digest, Digest::SHA::PurePerl
386 The Secure Hash Standard (FIPS PUB 180-2) can be found at:
388 http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf
390 <http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf>
391 The Keyed-Hash Message Authentication Code (HMAC):
393 http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf
395 <http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf>
396
398 Mark Shelor <mshelor@cpan.org>
399
401 The author is particularly grateful to
402 Gisle Aas
404 Chris Carey
405 Alexandr Ciornii
406 Jim Doble
407 Julius Duque
408 Jeffrey Friedl
409 Robert Gilmour
410 Brian Gladman
411 Adam Kennedy
412 Andy Lester
413 Alex Muntada
414 Steve Peters
415 Chris Skiscim
416 Martin Thurn
417 Gunnar Wolf
418 Adam Woodbury
419 for their valuable comments and suggestions.
421
423 Copyright (C) 2003-2008 Mark Shelor
424 This library is free software; you can redistribute it and/or modify it
426 under the same terms as Perl itself.
427 perlartistic
429perl v5.12.4 2011-06-07 Digest::SHA(3pm)