1Digest::SHA(3) User Contributed Perl Documentation Digest::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
62 Standard. It gives Perl programmers a convenient way to calculate
63 SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, and SHA-512/256
64 message digests. The module can handle all types of input, including
65 partial-byte data.
66
68 Digest::SHA is written in C for speed. If your platform lacks a C
69 compiler, you can install the functionally equivalent (but much slower)
70 Digest::SHA::PurePerl module.
71 The programming interface is easy to use: it's the same one found in
73 CPAN's Digest module. So, if your applications currently use
74 Digest::MD5 and you'd prefer the stronger security of SHA, it's a
75 simple matter to convert them.
76 The interface provides two ways to calculate digests: all-at-once, or
78 in stages. To illustrate, the following short program computes the
79 SHA-256 digest of "hello world" using each approach:
80 use Digest::SHA qw(sha256_hex);
82 $data = "hello world";
84 @frags = split(//, $data);
85 # all-at-once (Functional style)
87 $digest1 = sha256_hex($data);
88 # in-stages (OOP style)
90 $state = Digest::SHA->new(256);
91 for (@frags) { $state->add($_) }
92 $digest2 = $state->hexdigest;
93 print $digest1 eq $digest2 ?
95 "whew!\n" : "oops!\n";
96 To calculate the digest of an n-bit message where n is not a multiple
98 of 8, use the add_bits() method. For example, consider the 446-bit
99 message consisting of the bit-string "110" repeated 148 times, followed
100 by "11". Here's how to display its SHA-1 digest:
101 use Digest::SHA;
103 $bits = "110" x 148 . "11";
104 $sha = Digest::SHA->new(1)->add_bits($bits);
105 print $sha->hexdigest, "\n";
106 Note that for larger bit-strings, it's more efficient to use the two-
108 argument version add_bits($data, $nbits), where $data is in the
109 customary packed binary format used for Perl strings.
110 The module also lets you save intermediate SHA states to disk, or
112 display them on standard output. The dump() method generates portable,
113 human-readable text describing the current state of computation. You
114 can subsequently retrieve the file with load() to resume where the
115 calculation left off.
116 To see what a state description looks like, just run the following:
118 use Digest::SHA;
120 Digest::SHA->new->add("Shaw" x 1962)->dump;
121 As an added convenience, the Digest::SHA module offers routines to
123 calculate keyed hashes using the HMAC-SHA-1/224/256/384/512 algorithms.
124 These services exist in functional form only, and mimic the style and
125 behavior of the sha(), sha_hex(), and sha_base64() functions.
126 # Test vector from draft-ietf-ipsec-ciph-sha-256-01.txt
128 use Digest::SHA qw(hmac_sha256_hex);
130 print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\n";
131
133 Perl supports Unicode strings as of version 5.6. Such strings may
134 contain wide characters, namely, characters whose ordinal values are
135 greater than 255. This can cause problems for digest algorithms such
136 as SHA that are specified to operate on sequences of bytes.
137 The rule by which Digest::SHA handles a Unicode string is easy to
139 state, but potentially confusing to grasp: the string is interpreted as
140 a sequence of byte values, where each byte value is equal to the
141 ordinal value (viz. code point) of its corresponding Unicode character.
142 That way, the Unicode string 'abc' has exactly the same digest value as
143 the ordinary string 'abc'.
144 Since a wide character does not fit into a byte, the Digest::SHA
146 routines croak if they encounter one. Whereas if a Unicode string
147 contains no wide characters, the module accepts it quite happily. The
148 following code illustrates the two cases:
149 $str1 = pack('U*', (0..255));
151 print sha1_hex($str1); # ok
152 $str2 = pack('U*', (0..256));
154 print sha1_hex($str2); # croaks
155 Be aware that the digest routines silently convert UTF-8 input into its
157 equivalent byte sequence in the native encoding (cf. utf8::downgrade).
158 This side effect influences only the way Perl stores the data
159 internally, but otherwise leaves the actual value of the data intact.
160
162 NIST acknowledges that the work of Prof. Xiaoyun Wang constitutes a
163 practical collision attack on SHA-1. Therefore, NIST encourages the
164 rapid adoption of the SHA-2 hash functions (e.g. SHA-256) for
165 applications requiring strong collision resistance, such as digital
166 signatures.
167 ref. <http://csrc.nist.gov/groups/ST/hash/statement.html>
169
171 By convention, CPAN Digest modules do not pad their Base64 output.
172 Problems can occur when feeding such digests to other software that
173 expects properly padded Base64 encodings.
174 For the time being, any necessary padding must be done by the user.
176 Fortunately, this is a simple operation: if the length of a
177 Base64-encoded digest isn't a multiple of 4, simply append "="
178 characters to the end of the digest until it is:
179 while (length($b64_digest) % 4) {
181 $b64_digest .= '=';
182 }
183 To illustrate, sha256_base64("abc") is computed to be
185 ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0
187 which has a length of 43. So, the properly padded version is
189 ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
191
193 None by default.
194
196 Provided your C compiler supports a 64-bit type (e.g. the long long of
197 C99, or __int64 used by Microsoft C/C++), all of these functions will
198 be available for use. Otherwise, you won't be able to perform the
199 SHA-384 and SHA-512 transforms, both of which require 64-bit
200 operations.
201 Functional style
203 sha1($data, ...)
205 sha224($data, ...)
206 sha256($data, ...)
207 sha384($data, ...)
208 sha512($data, ...)
209 sha512224($data, ...)
210 sha512256($data, ...)
211 Logically joins the arguments into a single string, and returns its
212 SHA-1/224/256/384/512 digest encoded as a binary string.
213 sha1_hex($data, ...)
215 sha224_hex($data, ...)
216 sha256_hex($data, ...)
217 sha384_hex($data, ...)
218 sha512_hex($data, ...)
219 sha512224_hex($data, ...)
220 sha512256_hex($data, ...)
221 Logically joins the arguments into a single string, and returns its
222 SHA-1/224/256/384/512 digest encoded as a hexadecimal string.
223 sha1_base64($data, ...)
225 sha224_base64($data, ...)
226 sha256_base64($data, ...)
227 sha384_base64($data, ...)
228 sha512_base64($data, ...)
229 sha512224_base64($data, ...)
230 sha512256_base64($data, ...)
231 Logically joins the arguments into a single string, and returns its
232 SHA-1/224/256/384/512 digest encoded as a Base64 string.
233 It's important to note that the resulting string does not contain
235 the padding characters typical of Base64 encodings. This omission
236 is deliberate, and is done to maintain compatibility with the
237 family of CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for
238 details.
239 OOP style
241 new($alg)
243 Returns a new Digest::SHA object. Allowed values for $alg are 1,
244 224, 256, 384, 512, 512224, or 512256. It's also possible to use
245 common string representations of the algorithm (e.g. "sha256",
246 "SHA-384"). If the argument is missing, SHA-1 will be used by
247 default.
248 Invoking new as an instance method will not create a new object;
250 instead, it will simply reset the object to the initial state
251 associated with $alg. If the argument is missing, the object will
252 continue using the same algorithm that was selected at creation.
253 reset($alg)
255 This method has exactly the same effect as new($alg). In fact,
256 reset is just an alias for new.
257 hashsize
259 Returns the number of digest bits for this object. The values are
260 160, 224, 256, 384, 512, 224, and 256 for SHA-1, SHA-224, SHA-256,
261 SHA-384, SHA-512, SHA-512/224 and SHA-512/256, respectively.
262 algorithm
264 Returns the digest algorithm for this object. The values are 1,
265 224, 256, 384, 512, 512224, and 512256 for SHA-1, SHA-224, SHA-256,
266 SHA-384, SHA-512, SHA-512/224, and SHA-512/256, respectively.
267 clone
269 Returns a duplicate copy of the object.
270 add($data, ...)
272 Logically joins the arguments into a single string, and uses it to
273 update the current digest state. In other words, the following
274 statements have the same effect:
275 $sha->add("a"); $sha->add("b"); $sha->add("c");
277 $sha->add("a")->add("b")->add("c");
278 $sha->add("a", "b", "c");
279 $sha->add("abc");
280 The return value is the updated object itself.
282 add_bits($data, $nbits)
284 add_bits($bits)
285 Updates the current digest state by appending bits to it. The
286 return value is the updated object itself.
287 The first form causes the most-significant $nbits of $data to be
289 appended to the stream. The $data argument is in the customary
290 binary format used for Perl strings.
291 The second form takes an ASCII string of "0" and "1" characters as
293 its argument. It's equivalent to
294 $sha->add_bits(pack("B*", $bits), length($bits));
296 So, the following two statements do the same thing:
298 $sha->add_bits("111100001010");
300 $sha->add_bits("\xF0\xA0", 12);
301 addfile(*FILE)
303 Reads from FILE until EOF, and appends that data to the current
304 state. The return value is the updated object itself.
305 addfile($filename [, $mode])
307 Reads the contents of $filename, and appends that data to the
308 current state. The return value is the updated object itself.
309 By default, $filename is simply opened and read; no special modes
311 or I/O disciplines are used. To change this, set the optional
312 $mode argument to one of the following values:
313 "b" read file in binary mode
315 "p" use portable mode
317 "0" use BITS mode
319 The "p" mode ensures that the digest value of $filename will be the
321 same when computed on different operating systems. It accomplishes
322 this by internally translating all newlines in text files to UNIX
323 format before calculating the digest. Binary files are read in raw
324 mode with no translation whatsoever.
325 The BITS mode ("0") interprets the contents of $filename as a
327 logical stream of bits, where each ASCII '0' or '1' character
328 represents a 0 or 1 bit, respectively. All other characters are
329 ignored. This provides a convenient way to calculate the digest
330 values of partial-byte data by using files, rather than having to
331 write programs using the add_bits method.
332 dump($filename)
334 Provides persistent storage of intermediate SHA states by writing a
335 portable, human-readable representation of the current state to
336 $filename. If the argument is missing, or equal to the empty
337 string, the state information will be written to STDOUT.
338 load($filename)
340 Returns a Digest::SHA object representing the intermediate SHA
341 state that was previously dumped to $filename. If called as a
342 class method, a new object is created; if called as an instance
343 method, the object is reset to the state contained in $filename.
344 If the argument is missing, or equal to the empty string, the state
345 information will be read from STDIN.
346 digest
348 Returns the digest encoded as a binary string.
349 Note that the digest method is a read-once operation. Once it has
351 been performed, the Digest::SHA object is automatically reset in
352 preparation for calculating another digest value. Call
353 $sha->clone->digest if it's necessary to preserve the original
354 digest state.
355 hexdigest
357 Returns the digest encoded as a hexadecimal string.
358 Like digest, this method is a read-once operation. Call
360 $sha->clone->hexdigest if it's necessary to preserve the original
361 digest state.
362 This method is inherited if Digest::base is installed on your
364 system. Otherwise, a functionally equivalent substitute is used.
365 b64digest
367 Returns the digest encoded as a Base64 string.
368 Like digest, this method is a read-once operation. Call
370 $sha->clone->b64digest if it's necessary to preserve the original
371 digest state.
372 This method is inherited if Digest::base is installed on your
374 system. Otherwise, a functionally equivalent substitute is used.
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
379 family of CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for
380 details.
381 HMAC-SHA-1/224/256/384/512
383 hmac_sha1($data, $key)
385 hmac_sha224($data, $key)
386 hmac_sha256($data, $key)
387 hmac_sha384($data, $key)
388 hmac_sha512($data, $key)
389 hmac_sha512224($data, $key)
390 hmac_sha512256($data, $key)
391 Returns the HMAC-SHA-1/224/256/384/512 digest of $data/$key, with
392 the result encoded as a binary string. Multiple $data arguments
393 are allowed, provided that $key is the last argument in the list.
394 hmac_sha1_hex($data, $key)
396 hmac_sha224_hex($data, $key)
397 hmac_sha256_hex($data, $key)
398 hmac_sha384_hex($data, $key)
399 hmac_sha512_hex($data, $key)
400 hmac_sha512224_hex($data, $key)
401 hmac_sha512256_hex($data, $key)
402 Returns the HMAC-SHA-1/224/256/384/512 digest of $data/$key, with
403 the result encoded as a hexadecimal string. Multiple $data
404 arguments are allowed, provided that $key is the last argument in
405 the list.
406 hmac_sha1_base64($data, $key)
408 hmac_sha224_base64($data, $key)
409 hmac_sha256_base64($data, $key)
410 hmac_sha384_base64($data, $key)
411 hmac_sha512_base64($data, $key)
412 hmac_sha512224_base64($data, $key)
413 hmac_sha512256_base64($data, $key)
414 Returns the HMAC-SHA-1/224/256/384/512 digest of $data/$key, with
415 the result encoded as a Base64 string. Multiple $data arguments
416 are allowed, provided that $key is the last argument in the list.
417 It's important to note that the resulting string does not contain
419 the padding characters typical of Base64 encodings. This omission
420 is deliberate, and is done to maintain compatibility with the
421 family of CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for
422 details.
423
425 Digest, Digest::SHA::PurePerl
426 The Secure Hash Standard (Draft FIPS PUB 180-4) can be found at:
428 <http://csrc.nist.gov/publications/drafts/fips180-4/Draft-FIPS180-4_Feb2011.pdf>
430 The Keyed-Hash Message Authentication Code (HMAC):
432 <http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf>
434
436 Mark Shelor <mshelor@cpan.org>
437
439 The author is particularly grateful to
440 Gisle Aas
442 Sean Burke
443 Chris Carey
444 Alexandr Ciornii
445 Jim Doble
446 Thomas Drugeon
447 Julius Duque
448 Jeffrey Friedl
449 Robert Gilmour
450 Brian Gladman
451 Adam Kennedy
452 Andy Lester
453 Alex Muntada
454 Steve Peters
455 Chris Skiscim
456 Martin Thurn
457 Gunnar Wolf
458 Adam Woodbury
459 "who by trained skill rescued life from such great billows and such
461 thick darkness and moored it in so perfect a calm and in so brilliant a
462 light" - Lucretius
463
465 Copyright (C) 2003-2013 Mark Shelor
466 This library is free software; you can redistribute it and/or modify it
468 under the same terms as Perl itself.
469 perlartistic
471perl v5.16.3 2013-06-26 Digest::SHA(3)