1Digest::SHA(3)        User Contributed Perl Documentation       Digest::SHA(3)
2
3
4

NAME

6       Digest::SHA - Perl extension for SHA-1/224/256/384/512
7

SYNOPSIS

9       In programs:
10
11                       # Functional interface
12
13               use Digest::SHA qw(sha1 sha1_hex sha1_base64 ...);
14
15               $digest = sha1($data);
16               $digest = sha1_hex($data);
17               $digest = sha1_base64($data);
18
19               $digest = sha256($data);
20               $digest = sha384_hex($data);
21               $digest = sha512_base64($data);
22
23                       # Object-oriented
24
25               use Digest::SHA;
26
27               $sha = Digest::SHA->new($alg);
28
29               $sha->add($data);               # feed data into stream
30
31               $sha->addfile(*F);
32               $sha->addfile($filename);
33
34               $sha->add_bits($bits);
35               $sha->add_bits($data, $nbits);
36
37               $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
41               $digest = $sha->digest;         # compute digest
42               $digest = $sha->hexdigest;
43               $digest = $sha->b64digest;
44
45       From the command line:
46
47               $ shasum files
48
49               $ shasum --help
50

SYNOPSIS (HMAC-SHA)

52                       # Functional interface only
53
54               use Digest::SHA qw(hmac_sha1 hmac_sha1_hex ...);
55
56               $digest = hmac_sha1($data, $key);
57               $digest = hmac_sha224_hex($data, $key);
58               $digest = hmac_sha256_base64($data, $key);
59

ABSTRACT

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

DESCRIPTION

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
72       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
77       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
81               use Digest::SHA qw(sha256_hex);
82
83               $data = "hello world";
84               @frags = split(//, $data);
85
86               # all-at-once (Functional style)
87               $digest1 = sha256_hex($data);
88
89               # in-stages (OOP style)
90               $state = Digest::SHA->new(256);
91               for (@frags) { $state->add($_) }
92               $digest2 = $state->hexdigest;
93
94               print $digest1 eq $digest2 ?
95                       "whew!\n" : "oops!\n";
96
97       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
102               use Digest::SHA;
103               $bits = "110" x 148 . "11";
104               $sha = Digest::SHA->new(1)->add_bits($bits);
105               print $sha->hexdigest, "\n";
106
107       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
111       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
116       To see what a state description looks like, just run the following:
117
118               use Digest::SHA;
119               print Digest::SHA->new->add("Shaw" x 1962)->getstate;
120
121       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
126               # Test vector from draft-ietf-ipsec-ciph-sha-256-01.txt
127
128               use Digest::SHA qw(hmac_sha256_hex);
129               print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\n";
130

UNICODE AND SIDE EFFECTS

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
137       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
144       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
149               $str1 = pack('U*', (0..255));
150               print sha1_hex($str1);          # ok
151
152               $str2 = pack('U*', (0..256));
153               print sha1_hex($str2);          # croaks
154
155       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

NIST STATEMENT ON SHA-1

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
167       ref. <http://csrc.nist.gov/groups/ST/hash/statement.html>
168

PADDING OF BASE64 DIGESTS

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
174       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
179               while (length($b64_digest) % 4) {
180                       $b64_digest .= '=';
181               }
182
183       To illustrate, sha256_base64("abc") is computed to be
184
185               ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0
186
187       which has a length of 43.  So, the properly padded version is
188
189               ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
190

EXPORT

192       None by default.
193

EXPORTABLE FUNCTIONS

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
201       Functional style
202
203       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
213       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
223       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
233           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
239       OOP style
240
241       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
248           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
253       reset($alg)
254           This method has exactly the same effect as new($alg).  In fact,
255           reset is just an alias for new.
256
257       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
262       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
267       clone
268           Returns a duplicate copy of the object.
269
270       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
275                   $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
280           The return value is the updated object itself.
281
282       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
287           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
291           The second form takes an ASCII string of "0" and "1" characters as
292           its argument.  It's equivalent to
293
294                   $sha->add_bits(pack("B*", $bits), length($bits));
295
296           So, the following two statements do the same thing:
297
298                   $sha->add_bits("111100001010");
299                   $sha->add_bits("\xF0\xA0", 12);
300
301           Note that SHA-1 and SHA-2 use most-significant-bit ordering for
302           their internal state.  This means that
303
304                   $sha3->add_bits("110");
305
306           is equivalent to
307
308                   $sha3->add_bits("1")->add_bits("1")->add_bits("0");
309
310       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
314       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
318           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
322                   "b"     read file in binary mode
323
324                   "U"     use universal newlines
325
326                   "0"     use BITS mode
327
328           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
336           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
343       getstate
344           Returns a string containing a portable, human-readable
345           representation of the current SHA state.
346
347       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
354       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
359       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
364       digest
365           Returns the digest encoded as a binary string.
366
367           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
373       hexdigest
374           Returns the digest encoded as a hexadecimal string.
375
376           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
380       b64digest
381           Returns the digest encoded as a Base64 string.
382
383           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
387           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
393       HMAC-SHA-1/224/256/384/512
394
395       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
406       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
418       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
429           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

SEE ALSO

436       Digest, Digest::SHA::PurePerl
437
438       The Secure Hash Standard (Draft FIPS PUB 180-4) can be found at:
439
440       <http://csrc.nist.gov/publications/drafts/fips180-4/Draft-FIPS180-4_Feb2011.pdf>
441
442       The Keyed-Hash Message Authentication Code (HMAC):
443
444       <http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf>
445

AUTHOR

447               Mark Shelor     <mshelor@cpan.org>
448

ACKNOWLEDGMENTS

450       The author is particularly grateful to
451
452               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
475       "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-2022 Mark Shelor
481
482       This library is free software; you can redistribute it and/or modify it
483       under the same terms as Perl itself.
484
485       perlartistic
486
487
488
489perl v5.36.0                      2023-02-26                    Digest::SHA(3)
Impressum