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; # make copy of digest object
38 $state = $sha->getstate; # save current state to string
39 $sha->putstate($state); # restore previous $state
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 a string. The
112 getstate() method generates portable, human-readable text describing
113 the current state of computation. You can subsequently restore that
114 state with putstate() to resume where the calculation left off.
115 To see what a state description looks like, just run the following:
117 use Digest::SHA;
119 print Digest::SHA->new->add("Shaw" x 1962)->getstate;
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 Perl supports Unicode strings as of version 5.6. Such strings may
133 contain wide characters, namely, characters whose ordinal values are
134 greater than 255. This can cause problems for digest algorithms such
135 as SHA that are specified to operate on sequences of bytes.
136 The rule by which Digest::SHA handles a Unicode string is easy to
138 state, but potentially confusing to grasp: the string is interpreted as
139 a sequence of byte values, where each byte value is equal to the
140 ordinal value (viz. code point) of its corresponding Unicode character.
141 That way, the Unicode string 'abc' has exactly the same digest value as
142 the ordinary string 'abc'.
143 Since a wide character does not fit into a byte, the Digest::SHA
145 routines croak if they encounter one. Whereas if a Unicode string
146 contains no wide characters, the module accepts it quite happily. The
147 following code illustrates the two cases:
148 $str1 = pack('U*', (0..255));
150 print sha1_hex($str1); # ok
151 $str2 = pack('U*', (0..256));
153 print sha1_hex($str2); # croaks
154 Be aware that the digest routines silently convert UTF-8 input into its
156 equivalent byte sequence in the native encoding (cf. utf8::downgrade).
157 This side effect influences only the way Perl stores the data
158 internally, but otherwise leaves the actual value of the data intact.
159
161 NIST acknowledges that the work of Prof. Xiaoyun Wang constitutes a
162 practical collision attack on SHA-1. Therefore, NIST encourages the
163 rapid adoption of the SHA-2 hash functions (e.g. SHA-256) for
164 applications requiring strong collision resistance, such as digital
165 signatures.
166 ref. <http://csrc.nist.gov/groups/ST/hash/statement.html>
168
170 By convention, CPAN Digest modules do not pad their Base64 output.
171 Problems can occur when feeding such digests to other software that
172 expects properly padded Base64 encodings.
173 For the time being, any necessary padding must be done by the user.
175 Fortunately, this is a simple operation: if the length of a
176 Base64-encoded digest isn't a multiple of 4, simply append "="
177 characters to the end of the digest until it is:
178 while (length($b64_digest) % 4) {
180 $b64_digest .= '=';
181 }
182 To illustrate, sha256_base64("abc") is computed to be
184 ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0
186 which has a length of 43. So, the properly padded version is
188 ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
190
192 None by default.
193
195 Provided your C compiler supports a 64-bit type (e.g. the long long of
196 C99, or __int64 used by Microsoft C/C++), all of these functions will
197 be available for use. Otherwise, you won't be able to perform the
198 SHA-384 and SHA-512 transforms, both of which require 64-bit
199 operations.
200 Functional style
202 sha1($data, ...)
204 sha224($data, ...)
205 sha256($data, ...)
206 sha384($data, ...)
207 sha512($data, ...)
208 sha512224($data, ...)
209 sha512256($data, ...)
210 Logically joins the arguments into a single string, and returns its
211 SHA-1/224/256/384/512 digest encoded as a binary string.
212 sha1_hex($data, ...)
214 sha224_hex($data, ...)
215 sha256_hex($data, ...)
216 sha384_hex($data, ...)
217 sha512_hex($data, ...)
218 sha512224_hex($data, ...)
219 sha512256_hex($data, ...)
220 Logically joins the arguments into a single string, and returns its
221 SHA-1/224/256/384/512 digest encoded as a hexadecimal string.
222 sha1_base64($data, ...)
224 sha224_base64($data, ...)
225 sha256_base64($data, ...)
226 sha384_base64($data, ...)
227 sha512_base64($data, ...)
228 sha512224_base64($data, ...)
229 sha512256_base64($data, ...)
230 Logically joins the arguments into a single string, and returns its
231 SHA-1/224/256/384/512 digest encoded as a Base64 string.
232 It's important to note that the resulting string does not contain
234 the padding characters typical of Base64 encodings. This omission
235 is deliberate, and is done to maintain compatibility with the
236 family of CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for
237 details.
238 OOP style
240 new($alg)
242 Returns a new Digest::SHA object. Allowed values for $alg are 1,
243 224, 256, 384, 512, 512224, or 512256. It's also possible to use
244 common string representations of the algorithm (e.g. "sha256",
245 "SHA-384"). If the argument is missing, SHA-1 will be used by
246 default.
247 Invoking new as an instance method will reset the object to the
249 initial state associated with $alg. If the argument is missing,
250 the object will continue using the same algorithm that was selected
251 at creation.
252 reset($alg)
254 This method has exactly the same effect as new($alg). In fact,
255 reset is just an alias for new.
256 hashsize
258 Returns the number of digest bits for this object. The values are
259 160, 224, 256, 384, 512, 224, and 256 for SHA-1, SHA-224, SHA-256,
260 SHA-384, SHA-512, SHA-512/224 and SHA-512/256, respectively.
261 algorithm
263 Returns the digest algorithm for this object. The values are 1,
264 224, 256, 384, 512, 512224, and 512256 for SHA-1, SHA-224, SHA-256,
265 SHA-384, SHA-512, SHA-512/224, and SHA-512/256, respectively.
266 clone
268 Returns a duplicate copy of the object.
269 add($data, ...)
271 Logically joins the arguments into a single string, and uses it to
272 update the current digest state. In other words, the following
273 statements have the same effect:
274 $sha->add("a"); $sha->add("b"); $sha->add("c");
276 $sha->add("a")->add("b")->add("c");
277 $sha->add("a", "b", "c");
278 $sha->add("abc");
279 The return value is the updated object itself.
281 add_bits($data, $nbits)
283 add_bits($bits)
284 Updates the current digest state by appending bits to it. The
285 return value is the updated object itself.
286 The first form causes the most-significant $nbits of $data to be
288 appended to the stream. The $data argument is in the customary
289 binary format used for Perl strings.
290 The second form takes an ASCII string of "0" and "1" characters as
292 its argument. It's equivalent to
293 $sha->add_bits(pack("B*", $bits), length($bits));
295 So, the following two statements do the same thing:
297 $sha->add_bits("111100001010");
299 $sha->add_bits("\xF0\xA0", 12);
300 Note that SHA-1 and SHA-2 use most-significant-bit ordering for
302 their internal state. This means that
303 $sha3->add_bits("110");
305 is equivalent to
307 $sha3->add_bits("1")->add_bits("1")->add_bits("0");
309 addfile(*FILE)
311 Reads from FILE until EOF, and appends that data to the current
312 state. The return value is the updated object itself.
313 addfile($filename [, $mode])
315 Reads the contents of $filename, and appends that data to the
316 current state. The return value is the updated object itself.
317 By default, $filename is simply opened and read; no special modes
319 or I/O disciplines are used. To change this, set the optional
320 $mode argument to one of the following values:
321 "b" read file in binary mode
323 "U" use universal newlines
325 "0" use BITS mode
327 The "U" mode is modeled on Python's "Universal Newlines" concept,
329 whereby DOS and Mac OS line terminators are converted internally to
330 UNIX newlines before processing. This ensures consistent digest
331 values when working simultaneously across multiple file systems.
332 The "U" mode influences only text files, namely those passing
333 Perl's -T test; binary files are processed with no translation
334 whatsoever.
335 The BITS mode ("0") interprets the contents of $filename as a
337 logical stream of bits, where each ASCII '0' or '1' character
338 represents a 0 or 1 bit, respectively. All other characters are
339 ignored. This provides a convenient way to calculate the digest
340 values of partial-byte data by using files, rather than having to
341 write separate programs employing the add_bits method.
342 getstate
344 Returns a string containing a portable, human-readable
345 representation of the current SHA state.
346 putstate($str)
348 Returns a Digest::SHA object representing the SHA state contained
349 in $str. The format of $str matches the format of the output
350 produced by method getstate. If called as a class method, a new
351 object is created; if called as an instance method, the object is
352 reset to the state contained in $str.
353 dump($filename)
355 Writes the output of getstate to $filename. If the argument is
356 missing, or equal to the empty string, the state information will
357 be written to STDOUT.
358 load($filename)
360 Returns a Digest::SHA object that results from calling putstate on
361 the contents of $filename. If the argument is missing, or equal to
362 the empty string, the state information will be read from STDIN.
363 digest
365 Returns the digest encoded as a binary string.
366 Note that the digest method is a read-once operation. Once it has
368 been performed, the Digest::SHA object is automatically reset in
369 preparation for calculating another digest value. Call
370 $sha->clone->digest if it's necessary to preserve the original
371 digest state.
372 hexdigest
374 Returns the digest encoded as a hexadecimal string.
375 Like digest, this method is a read-once operation. Call
377 $sha->clone->hexdigest if it's necessary to preserve the original
378 digest state.
379 b64digest
381 Returns the digest encoded as a Base64 string.
382 Like digest, this method is a read-once operation. Call
384 $sha->clone->b64digest if it's necessary to preserve the original
385 digest state.
386 It's important to note that the resulting string does not contain
388 the padding characters typical of Base64 encodings. This omission
389 is deliberate, and is done to maintain compatibility with the
390 family of CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for
391 details.
392 HMAC-SHA-1/224/256/384/512
394 hmac_sha1($data, $key)
396 hmac_sha224($data, $key)
397 hmac_sha256($data, $key)
398 hmac_sha384($data, $key)
399 hmac_sha512($data, $key)
400 hmac_sha512224($data, $key)
401 hmac_sha512256($data, $key)
402 Returns the HMAC-SHA-1/224/256/384/512 digest of $data/$key, with
403 the result encoded as a binary string. Multiple $data arguments
404 are allowed, provided that $key is the last argument in the list.
405 hmac_sha1_hex($data, $key)
407 hmac_sha224_hex($data, $key)
408 hmac_sha256_hex($data, $key)
409 hmac_sha384_hex($data, $key)
410 hmac_sha512_hex($data, $key)
411 hmac_sha512224_hex($data, $key)
412 hmac_sha512256_hex($data, $key)
413 Returns the HMAC-SHA-1/224/256/384/512 digest of $data/$key, with
414 the result encoded as a hexadecimal string. Multiple $data
415 arguments are allowed, provided that $key is the last argument in
416 the list.
417 hmac_sha1_base64($data, $key)
419 hmac_sha224_base64($data, $key)
420 hmac_sha256_base64($data, $key)
421 hmac_sha384_base64($data, $key)
422 hmac_sha512_base64($data, $key)
423 hmac_sha512224_base64($data, $key)
424 hmac_sha512256_base64($data, $key)
425 Returns the HMAC-SHA-1/224/256/384/512 digest of $data/$key, with
426 the result encoded as a Base64 string. Multiple $data arguments
427 are allowed, provided that $key is the last argument in the list.
428 It's important to note that the resulting string does not contain
430 the padding characters typical of Base64 encodings. This omission
431 is deliberate, and is done to maintain compatibility with the
432 family of CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for
433 details.
434
436 Digest, Digest::SHA::PurePerl
437 The Secure Hash Standard (Draft FIPS PUB 180-4) can be found at:
439 <http://csrc.nist.gov/publications/drafts/fips180-4/Draft-FIPS180-4_Feb2011.pdf>
441 The Keyed-Hash Message Authentication Code (HMAC):
443 <http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf>
445
447 Mark Shelor <mshelor@cpan.org>
448
450 The author is particularly grateful to
451 Gisle Aas
453 H. Merijn Brand
454 Sean Burke
455 Chris Carey
456 Alexandr Ciornii
457 Chris David
458 Jim Doble
459 Thomas Drugeon
460 Julius Duque
461 Jeffrey Friedl
462 Robert Gilmour
463 Brian Gladman
464 Jarkko Hietaniemi
465 Adam Kennedy
466 Mark Lawrence
467 Andy Lester
468 Alex Muntada
469 Steve Peters
470 Chris Skiscim
471 Martin Thurn
472 Gunnar Wolf
473 Adam Woodbury
474 "who by trained skill rescued life from such great billows and such
476 thick darkness and moored it in so perfect a calm and in so brilliant a
477 light" - Lucretius
478
480 Copyright (C) 2003-2018 Mark Shelor
481 This library is free software; you can redistribute it and/or modify it
483 under the same terms as Perl itself.
484 perlartistic
486perl v5.26.3 2018-04-20 Digest::SHA(3)