1SHA(3) User Contributed Perl Documentation SHA(3)
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 Stan‐
62 dard. It gives Perl programmers a convenient way to calculate SHA-1,
63 SHA-224, SHA-256, SHA-384, and SHA-512 message digests. The module can
64 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 com‐
68 piler, 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 sim‐
74 ple 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 custom‐
108 ary packed binary format used for Perl strings.
109 The module also lets you save intermediate SHA states to disk, or dis‐
111 play 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 cal‐
114 culation 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 cal‐
122 culate 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 algo‐
134 rithm, which has been in effect since 1994. The researchers have not
135 yet published their complete results, so NIST has not confirmed these
136 findings. However, the researchers are a reputable research team with
137 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. <http://www.csrc.nist.gov/pki/HashWorkshop/NIST%20State‐
145 ment/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 "=" charac‐
155 ters 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 opera‐
177 tions.
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 fam‐
208 ily of CPAN Digest modules. See "BASE64 DIGESTS" for details.
209 OOP style
211 new($alg)
213 Returns a new Digest::SHA object. Allowed values for $alg are 1,
214 224, 256, 384, or 512. It's also possible to use common string
215 representations of the algorithm (e.g. "sha256", "SHA-384"). If
216 the argument is missing, SHA-1 will be used by default.
217 Invoking new as an instance method will not create a new object;
219 instead, it will simply reset the object to the initial state asso‐
220 ciated with $alg. If the argument is missing, the object will con‐
221 tinue using the same algorithm that was selected at creation.
222 reset($alg)
224 This method has exactly the same effect as new($alg). In fact,
225 reset is just an alias for new.
226 hashsize
228 Returns the number of digest bits for this object. The values are
229 160, 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384,
230 and SHA-512, respectively.
231 algorithm
233 Returns the digest algorithm for this object. The values are 1,
234 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384, and
235 SHA-512, respectively.
236 clone
238 Returns a duplicate copy of the object.
239 add($data, ...)
241 Logically joins the arguments into a single string, and uses it to
242 update the current digest state. In other words, the following
243 statements have the same effect:
244 $sha->add("a"); $sha->add("b"); $sha->add("c");
246 $sha->add("a")->add("b")->add("c");
247 $sha->add("a", "b", "c");
248 $sha->add("abc");
249 The return value is the updated object itself.
251 add_bits($data, $nbits)
253 add_bits($bits)
254 Updates the current digest state by appending bits to it. The
255 return value is the updated object itself.
256 The first form causes the most-significant $nbits of $data to be
258 appended to the stream. The $data argument is in the customary
259 binary format used for Perl strings.
260 The second form takes an ASCII string of "0" and "1" characters as
262 its argument. It's equivalent to
263 $sha->add_bits(pack("B*", $bits), length($bits));
265 So, the following two statements do the same thing:
267 $sha->add_bits("111100001010");
269 $sha->add_bits("\xF0\xA0", 12);
270 addfile(*FILE)
272 Reads from FILE until EOF, and appends that data to the current
273 state. The return value is the updated object itself.
274 addfile($filename [, $mode])
276 Reads the contents of $filename, and appends that data to the cur‐
277 rent state. The return value is the updated object itself.
278 By default, $filename is simply opened and read; no special modes
280 or I/O disciplines are used. To change this, set the optional
281 $mode argument to one of the following values:
282 "b" read file in binary mode
284 "p" use portable mode
286 The "p" mode is handy since it ensures that the digest value of
288 $filename will be the same when computed on different operating
289 systems. It accomplishes this by internally translating all new‐
290 lines in text files to UNIX format before calculating the digest;
291 on the other hand, binary files are read in raw mode with no trans‐
292 lation whatsoever.
293 For a fuller discussion of newline formats, refer to CPAN module
295 File::LocalizeNewlines. Its "universal line separator" regex forms
296 the basis of addfile's portable mode processing.
297 dump($filename)
299 Provides persistent storage of intermediate SHA states by writing a
300 portable, human-readable representation of the current state to
301 $filename. If the argument is missing, or equal to the empty
302 string, the state information will be written to STDOUT.
303 load($filename)
305 Returns a Digest::SHA object representing the intermediate SHA
306 state that was previously dumped to $filename. If called as a
307 class method, a new object is created; if called as an instance
308 method, the object is reset to the state contained in $filename.
309 If the argument is missing, or equal to the empty string, the state
310 information will be read from STDIN.
311 digest
313 Returns the digest encoded as a binary string.
314 Note that the digest method is a read-once operation. Once it has
316 been performed, the Digest::SHA object is automatically reset in
317 preparation for calculating another digest value. Call
318 $sha->clone->digest if it's necessary to preserve the original
319 digest state.
320 hexdigest
322 Returns the digest encoded as a hexadecimal string.
323 Like digest, this method is a read-once operation. Call
325 $sha->clone->hexdigest if it's necessary to preserve the original
326 digest state.
327 This method is inherited if Digest::base is installed on your sys‐
329 tem. Otherwise, a functionally equivalent substitute is used.
330 b64digest
332 Returns the digest encoded as a Base64 string.
333 Like digest, this method is a read-once operation. Call
335 $sha->clone->b64digest if it's necessary to preserve the original
336 digest state.
337 This method is inherited if Digest::base is installed on your sys‐
339 tem. Otherwise, a functionally equivalent substitute is used.
340 It's important to note that the resulting string does not contain
342 the padding characters typical of Base64 encodings. This omission
343 is deliberate, and is done to maintain compatibility with the fam‐
344 ily of CPAN Digest modules. See "BASE64 DIGESTS" for details.
345 HMAC-SHA-1/224/256/384/512
347 hmac_sha1($data, $key)
349 hmac_sha224($data, $key)
350 hmac_sha256($data, $key)
351 hmac_sha384($data, $key)
352 hmac_sha512($data, $key)
353 Returns the HMAC-SHA-1/224/256/384/512 digest of $data/$key, with
354 the result encoded as a binary string. Multiple $data arguments
355 are allowed, provided that $key is the last argument in the list.
356 hmac_sha1_hex($data, $key)
358 hmac_sha224_hex($data, $key)
359 hmac_sha256_hex($data, $key)
360 hmac_sha384_hex($data, $key)
361 hmac_sha512_hex($data, $key)
362 Returns the HMAC-SHA-1/224/256/384/512 digest of $data/$key, with
363 the result encoded as a hexadecimal string. Multiple $data argu‐
364 ments are allowed, provided that $key is the last argument in the
365 list.
366 hmac_sha1_base64($data, $key)
368 hmac_sha224_base64($data, $key)
369 hmac_sha256_base64($data, $key)
370 hmac_sha384_base64($data, $key)
371 hmac_sha512_base64($data, $key)
372 Returns the HMAC-SHA-1/224/256/384/512 digest of $data/$key, with
373 the result encoded as a Base64 string. Multiple $data arguments
374 are allowed, provided that $key is the last argument in the list.
375 It's important to note that the resulting string does not contain
377 the padding characters typical of Base64 encodings. This omission
378 is deliberate, and is done to maintain compatibility with the fam‐
379 ily of CPAN Digest modules. See "BASE64 DIGESTS" for details.
380
382 Digest, Digest::SHA::PurePerl
383 The Secure Hash Standard (FIPS PUB 180-2) can be found at:
385 <http://csrc.nist.gov/publications/fips/fips180-2/fips180-2with‐
387 changenotice.pdf>
388 The Keyed-Hash Message Authentication Code (HMAC):
390 <http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf>
392
394 Mark Shelor <mshelor@cpan.org>
395
397 The author is particularly grateful to
398 Gisle Aas
400 Chris Carey
401 Julius Duque
402 Jeffrey Friedl
403 Robert Gilmour
404 Brian Gladman
405 Adam Kennedy
406 Andy Lester
407 Alex Muntada
408 Steve Peters
409 Chris Skiscim
410 Martin Thurn
411 Gunnar Wolf
412 Adam Woodbury
413 for their valuable comments and suggestions.
415
417 Copyright (C) 2003-2006 Mark Shelor
418 This library is free software; you can redistribute it and/or modify it
420 under the same terms as Perl itself.
421 perlartistic
423perl v5.8.8 2006-10-14 SHA(3)