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

NAME

6       Digest::SHA3 - Perl extension for SHA-3
7

SYNOPSIS

9       In programs:
10
11                       # Functional interface
12
13               use Digest::SHA3 qw(sha3_224 sha3_256_hex sha3_512_base64 ...);
14
15               $digest = sha3_224($data);
16               $digest = sha3_256_hex($data);
17               $digest = sha3_384_base64($data);
18               $digest = sha3_512($data);
19
20                       # Object-oriented
21
22               use Digest::SHA3;
23
24               $sha3 = Digest::SHA3->new($alg);
25
26               $sha3->add($data);              # feed data into stream
27
28               $sha3->addfile(*F);
29               $sha3->addfile($filename);
30
31               $sha3->add_bits($bits);
32               $sha3->add_bits($data, $nbits);
33
34               $digest = $sha3->digest;        # compute digest
35               $digest = $sha3->hexdigest;
36               $digest = $sha3->b64digest;
37
38                       # Compute extendable-length digest
39
40               $sha3 = Digest::SHA3->new(128000)->add($data);  # SHAKE128
41               $digest  = $sha3->squeeze;
42               $digest .= $sha3->squeeze;
43               ...
44
45               $sha3 = Digest::SHA3->new(256000)->add($data);  # SHAKE256
46               $digest  = $sha3->squeeze;
47               $digest .= $sha3->squeeze;
48               ...
49

ABSTRACT

51       Digest::SHA3 is a complete implementation of the NIST SHA-3
52       cryptographic hash function, as specified in FIPS 202 (SHA-3 Standard:
53       Permutation-Based Hash and Extendable-Output Functions).
54
55       The module gives Perl programmers a convenient way to calculate
56       SHA3-224, SHA3-256, SHA3-384, and SHA3-512 message digests, as well as
57       variable-length hashes using SHAKE128 and SHAKE256.  Digest::SHA3 can
58       handle all types of input, including partial-byte data.
59

DESCRIPTION

61       Digest::SHA3 is written in C for speed.  If your platform lacks a C
62       compiler, perhaps you can find the module in a binary form compatible
63       with your particular processor and operating system.
64
65       The programming interface is easy to use: it's the same one found in
66       CPAN's Digest module.  So, if your applications currently use
67       Digest::SHA and you'd prefer the newer flavor of the NIST standard,
68       it's a simple matter to convert them.
69
70       The interface provides two ways to calculate digests:  all-at-once, or
71       in stages.  To illustrate, the following short program computes the
72       SHA3-256 digest of "hello world" using each approach:
73
74               use Digest::SHA3 qw(sha3_256_hex);
75
76               $data = "hello world";
77               @frags = split(//, $data);
78
79               # all-at-once (Functional style)
80               $digest1 = sha3_256_hex($data);
81
82               # in-stages (OOP style)
83               $state = Digest::SHA3->new(256);
84               for (@frags) { $state->add($_) }
85               $digest2 = $state->hexdigest;
86
87               print $digest1 eq $digest2 ?
88                       "that's the ticket!\n" : "oops!\n";
89
90       To calculate the digest of an n-bit message where n is not a multiple
91       of 8, use the add_bits() method.  For example, consider the 446-bit
92       message consisting of the bit-string "110" repeated 148 times, followed
93       by "11".  Here's how to display its SHA3-512 digest:
94
95               use Digest::SHA3;
96               $bits = "110" x 148 . "11";
97               $sha3 = Digest::SHA3->new(512)->add_bits($bits);
98               print $sha3->hexdigest, "\n";
99
100       Note that for larger bit-strings, it's more efficient to use the two-
101       argument version add_bits($data, $nbits), where $data is in the
102       customary packed binary format used for Perl strings.
103

UNICODE AND SIDE EFFECTS

105       Perl supports Unicode strings as of version 5.6.  Such strings may
106       contain wide characters: namely, characters whose ordinal values are
107       greater than 255.  This can cause problems for digest algorithms such
108       as SHA-3 that are specified to operate on sequences of bytes.
109
110       The rule by which Digest::SHA3 handles a Unicode string is easy to
111       state, but potentially confusing to grasp: the string is interpreted as
112       a sequence of byte values, where each byte value is equal to the
113       ordinal value (viz. code point) of its corresponding Unicode character.
114       That way, the Unicode string 'abc' has exactly the same digest value as
115       the ordinary string 'abc'.
116
117       Since a wide character does not fit into a byte, the Digest::SHA3
118       routines croak if they encounter one.  Whereas if a Unicode string
119       contains no wide characters, the module accepts it quite happily.  The
120       following code illustrates the two cases:
121
122               $str1 = pack('U*', (0..255));
123               print sha3_224_hex($str1);              # ok
124
125               $str2 = pack('U*', (0..256));
126               print sha3_224_hex($str2);              # croaks
127
128       Be aware that the digest routines silently convert UTF-8 input into its
129       equivalent byte sequence in the native encoding (cf. utf8::downgrade).
130       This side effect influences only the way Perl stores the data
131       internally, but otherwise leaves the actual value of the data intact.
132

PADDING OF BASE64 DIGESTS

134       By convention, CPAN Digest modules do not pad their Base64 output.
135       Problems can occur when feeding such digests to other software that
136       expects properly padded Base64 encodings.
137
138       For the time being, any necessary padding must be done by the user.
139       Fortunately, this is a simple operation: if the length of a
140       Base64-encoded digest isn't a multiple of 4, simply append "="
141       characters to the end of the digest until it is:
142
143               while (length($b64_digest) % 4) {
144                       $b64_digest .= '=';
145               }
146
147       To illustrate, sha3_256_base64("abc") is computed to be
148
149               Ophdp0/iJbIEXBcta9OQvYVfCG4+nVJbRr/iRRFDFTI
150
151       which has a length of 43.  So, the properly padded version is
152
153               Ophdp0/iJbIEXBcta9OQvYVfCG4+nVJbRr/iRRFDFTI=
154

EXPORT

156       None by default.
157

EXPORTABLE FUNCTIONS

159       Provided your C compiler supports a 64-bit type (e.g. the long long of
160       C99, or __int64 used by Microsoft C/C++), all of these functions will
161       be available for use.  Otherwise you won't be able to perform any of
162       them.
163
164       In the interest of simplicity, maintainability, and small code size,
165       it's unlikely that future versions of this module will support a 32-bit
166       implementation.  Older platforms using 32-bit-only compilers should
167       continue to favor 32-bit hash implementations such as SHA-1, SHA-224,
168       or SHA-256.  The desire to use the SHA-3 hash standard, dating from
169       2015, should reasonably require that one's compiler adhere to
170       programming language standards dating from at least 1999.
171
172       Functional style
173
174       sha3_224($data, ...)
175       sha3_256($data, ...)
176       sha3_384($data, ...)
177       sha3_512($data, ...)
178       shake128($data, ...)
179       shake256($data, ...)
180           Logically joins the arguments into a single string, and returns its
181           SHA3-0/224/256/384/512 digest encoded as a binary string.
182
183           The digest size for shake128 is 1344 bits (168 bytes); for
184           shake256, it's 1088 bits (136 bytes).  To obtain extendable-output
185           from the SHAKE algorithms, use the object-oriented interface with
186           repeated calls to the squeeze method.
187
188       sha3_224_hex($data, ...)
189       sha3_256_hex($data, ...)
190       sha3_384_hex($data, ...)
191       sha3_512_hex($data, ...)
192       shake128_hex($data, ...)
193       shake256_hex($data, ...)
194           Logically joins the arguments into a single string, and returns its
195           SHA3-0/224/256/384/512 or SHAKE128/256 digest encoded as a
196           hexadecimal string.
197
198       sha3_224_base64($data, ...)
199       sha3_256_base64($data, ...)
200       sha3_384_base64($data, ...)
201       sha3_512_base64($data, ...)
202       shake128_base64($data, ...)
203       shake256_base64($data, ...)
204           Logically joins the arguments into a single string, and returns its
205           SHA3-0/224/256/384/512 or SHAKE128/256 digest encoded as a Base64
206           string.
207
208           It's important to note that the resulting string does not contain
209           the padding characters typical of Base64 encodings.  This omission
210           is deliberate, and is done to maintain compatibility with the
211           family of CPAN Digest modules.  See "PADDING OF BASE64 DIGESTS" for
212           details.
213
214       OOP style
215
216       new($alg)
217           Returns a new Digest::SHA3 object.  Allowed values for $alg are
218           224, 256, 384, and 512 for the SHA3 algorithms; or 128000 and
219           256000 for SHAKE128 and SHAKE256, respectively.  If the argument is
220           missing, SHA3-224 will be used by default.
221
222           Invoking new as an instance method will not create a new object;
223           instead, it will simply reset the object to the initial state
224           associated with $alg.  If the argument is missing, the object will
225           continue using the same algorithm that was selected at creation.
226
227       reset($alg)
228           This method has exactly the same effect as new($alg).  In fact,
229           reset is just an alias for new.
230
231       hashsize
232           Returns the number of digest bits for this object.  The values are
233           224, 256, 384, 512, 1344, and 1088 for SHA3-224, SHA3-256,
234           SHA3-384, SHA3-512, SHAKE128, and SHAKE256, respectively.
235
236       algorithm
237           Returns the digest algorithm for this object.  The values are 224,
238           256, 384, 512, 128000, and 256000 for SHA3-224, SHA3-256, SHA3-384,
239           SHA3-512, SHAKE128, and SHAKE256, respectively.
240
241       clone
242           Returns a duplicate copy of the object.
243
244       add($data, ...)
245           Logically joins the arguments into a single string, and uses it to
246           update the current digest state.  In other words, the following
247           statements have the same effect:
248
249                   $sha3->add("a"); $sha3->add("b"); $sha3->add("c");
250                   $sha3->add("a")->add("b")->add("c");
251                   $sha3->add("a", "b", "c");
252                   $sha3->add("abc");
253
254           The return value is the updated object itself.
255
256       add_bits($data, $nbits [, $lsb])
257       add_bits($bits)
258           Updates the current digest state by appending bits to it.  The
259           return value is the updated object itself.
260
261           The first form causes the most-significant $nbits of $data to be
262           appended to the stream.  The $data argument is in the customary
263           binary format used for Perl strings.  Setting the optional $lsb
264           flag to a true value indicates that the final (partial) byte of
265           $data is aligned with the least-significant bit; by default it's
266           aligned with the most-significant bit, as required by the parent
267           Digest module.
268
269           The second form takes an ASCII string of "0" and "1" characters as
270           its argument.  It's equivalent to
271
272                   $sha3->add_bits(pack("B*", $bits), length($bits));
273
274           So, the following three statements do the same thing:
275
276                   $sha3->add_bits("111100001010");
277                   $sha3->add_bits("\xF0\xA0", 12);
278                   $sha3->add_bits("\xF0\x0A", 12, 1);
279
280           SHA-3 uses least-significant-bit ordering for its internal
281           operation.  This means that
282
283                   $sha3->add_bits("110");
284
285           is equivalent to
286
287                   $sha3->add_bits("0")->add_bits("1")->add_bits("1");
288
289           Many public test vectors for SHA-3, such as the Keccak known-answer
290           tests, are delivered in least-significant-bit format.  Using the
291           optional $lsb flag in these cases allows your code to be simpler
292           and more efficient.  See the test directory for examples.
293
294           The fact that SHA-2 and SHA-3 employ opposite bit-ordering schemes
295           has caused noticeable confusion in the programming community.
296           Exercise caution if your code examines individual bits in data
297           streams.
298
299       addfile(*FILE)
300           Reads from FILE until EOF, and appends that data to the current
301           state.  The return value is the updated object itself.
302
303       addfile($filename [, $mode])
304           Reads the contents of $filename, and appends that data to the
305           current state.  The return value is the updated object itself.
306
307           By default, $filename is simply opened and read; no special modes
308           or I/O disciplines are used.  To change this, set the optional
309           $mode argument to one of the following values:
310
311                   "b"     read file in binary mode
312
313                   "U"     use universal newlines
314
315                   "0"     use BITS mode
316
317           The "U" mode is modeled on Python's "Universal Newlines" concept,
318           whereby DOS and Mac OS line terminators are converted internally to
319           UNIX newlines before processing.  This ensures consistent digest
320           values when working simultaneously across multiple file systems.
321           The "U" mode influences only text files, namely those passing
322           Perl's -T test; binary files are processed with no translation
323           whatsoever.
324
325           The BITS mode ("0") interprets the contents of $filename as a
326           logical stream of bits, where each ASCII '0' or '1' character
327           represents a 0 or 1 bit, respectively.  All other characters are
328           ignored.  This provides a convenient way to calculate the digest
329           values of partial-byte data by using files, rather than having to
330           write programs using the add_bits method.
331
332       digest
333           Returns the digest encoded as a binary string.
334
335           Note that the digest method is a read-once operation. Once it has
336           been performed, the Digest::SHA3 object is automatically reset in
337           preparation for calculating another digest value.  Call
338           $sha->clone->digest if it's necessary to preserve the original
339           digest state.
340
341       hexdigest
342           Returns the digest encoded as a hexadecimal string.
343
344           Like digest, this method is a read-once operation.  Call
345           $sha->clone->hexdigest if it's necessary to preserve the original
346           digest state.
347
348       b64digest
349           Returns the digest encoded as a Base64 string.
350
351           Like digest, this method is a read-once operation.  Call
352           $sha->clone->b64digest if it's necessary to preserve the original
353           digest state.
354
355           It's important to note that the resulting string does not contain
356           the padding characters typical of Base64 encodings.  This omission
357           is deliberate, and is done to maintain compatibility with the
358           family of CPAN Digest modules.  See "PADDING OF BASE64 DIGESTS" for
359           details.
360
361       squeeze
362           Returns the next 168 (136) bytes of the SHAKE128 (SHAKE256) digest
363           encoded as a binary string.  The squeeze method may be called
364           repeatedly to construct digests of any desired length.
365
366           This method is applicable only to SHAKE128 and SHAKE256 objects.
367

SEE ALSO

369       Digest, Digest::SHA, Digest::Keccak
370
371       The FIPS 202 SHA-3 Standard can be found at:
372
373       <http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf>
374
375       The Keccak/SHA-3 specifications can be found at:
376
377       <http://keccak.noekeon.org/Keccak-reference-3.0.pdf>
378       <http://keccak.noekeon.org/Keccak-submission-3.pdf>
379

AUTHOR

381               Mark Shelor     <mshelor@cpan.org>
382

ACKNOWLEDGMENTS

384       The author is particularly grateful to
385
386               Guido Bertoni
387               Joan Daemen
388               Michael Peeters
389               Chris Skiscim
390               Gilles Van Assche
391
392       "Nothing is more fatiguing nor, in the long run, more exasperating than
393       the daily effort to believe things which daily become more incredible.
394       To be done with this effort is an indispensible condition of secure and
395       lasting happiness."  - Bertrand Russell
396
398       Copyright (C) 2012-2018 Mark Shelor
399
400       This library is free software; you can redistribute it and/or modify it
401       under the same terms as Perl itself.
402
403       perlartistic
404
405
406
407perl v5.32.0                      2020-07-28                   Digest::SHA3(3)
Impressum