1Digest::SHA3(3) User Contributed Perl Documentation Digest::SHA3(3)
2
6 Digest::SHA3 - Perl extension for SHA-3
7
9 In programs:
10 # Functional interface
12 use Digest::SHA3 qw(sha3_224 sha3_256_hex sha3_512_base64 ...);
14 $digest = sha3_224($data);
16 $digest = sha3_256_hex($data);
17 $digest = sha3_384_base64($data);
18 $digest = sha3_512($data);
19 # Object-oriented
21 use Digest::SHA3;
23 $sha3 = Digest::SHA3->new($alg);
25 $sha3->add($data); # feed data into stream
27 $sha3->addfile(*F);
29 $sha3->addfile($filename);
30 $sha3->add_bits($bits);
32 $sha3->add_bits($data, $nbits);
33 $digest = $sha3->digest; # compute digest
35 $digest = $sha3->hexdigest;
36 $digest = $sha3->b64digest;
37 # Compute extendable-length digest
39 $sha3 = Digest::SHA3->new(128000)->add($data); # SHAKE128
41 $digest = $sha3->squeeze;
42 $digest .= $sha3->squeeze;
43 ...
44 $sha3 = Digest::SHA3->new(256000)->add($data); # SHAKE256
46 $digest = $sha3->squeeze;
47 $digest .= $sha3->squeeze;
48 ...
49
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 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
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 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 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 use Digest::SHA3 qw(sha3_256_hex);
75 $data = "hello world";
77 @frags = split(//, $data);
78 # all-at-once (Functional style)
80 $digest1 = sha3_256_hex($data);
81 # in-stages (OOP style)
83 $state = Digest::SHA3->new(256);
84 for (@frags) { $state->add($_) }
85 $digest2 = $state->hexdigest;
86 print $digest1 eq $digest2 ?
88 "that's the ticket!\n" : "oops!\n";
89 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 use Digest::SHA3;
96 $bits = "110" x 148 . "11";
97 $sha3 = Digest::SHA3->new(512)->add_bits($bits);
98 print $sha3->hexdigest, "\n";
99 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
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 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 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 $str1 = pack('U*', (0..255));
123 print sha3_224_hex($str1); # ok
124 $str2 = pack('U*', (0..256));
126 print sha3_224_hex($str2); # croaks
127 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
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 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 while (length($b64_digest) % 4) {
144 $b64_digest .= '=';
145 }
146 To illustrate, sha3_256_base64("abc") is computed to be
148 Ophdp0/iJbIEXBcta9OQvYVfCG4+nVJbRr/iRRFDFTI
150 which has a length of 43. So, the properly padded version is
152 Ophdp0/iJbIEXBcta9OQvYVfCG4+nVJbRr/iRRFDFTI=
154
156 None by default.
157
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 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 Functional style
173 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 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 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 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 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 OOP style
215 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 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 reset($alg)
228 This method has exactly the same effect as new($alg). In fact,
229 reset is just an alias for new.
230 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 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 clone
242 Returns a duplicate copy of the object.
243 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 $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 The return value is the updated object itself.
255 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 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 The second form takes an ASCII string of "0" and "1" characters as
270 its argument. It's equivalent to
271 $sha3->add_bits(pack("B*", $bits), length($bits));
273 So, the following three statements do the same thing:
275 $sha3->add_bits("111100001010");
277 $sha3->add_bits("\xF0\xA0", 12);
278 $sha3->add_bits("\xF0\x0A", 12, 1);
279 SHA-3 uses least-significant-bit ordering for its internal
281 operation. This means that
282 $sha3->add_bits("110");
284 is equivalent to
286 $sha3->add_bits("0")->add_bits("1")->add_bits("1");
288 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 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 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 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 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 "b" read file in binary mode
312 "U" use universal newlines
314 "0" use BITS mode
316 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 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 digest
333 Returns the digest encoded as a binary string.
334 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 hexdigest
342 Returns the digest encoded as a hexadecimal string.
343 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 b64digest
349 Returns the digest encoded as a Base64 string.
350 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 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 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 This method is applicable only to SHAKE128 and SHAKE256 objects.
367
369 Digest, Digest::SHA, Digest::Keccak
370 The FIPS 202 SHA-3 Standard can be found at:
372 <http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf>
374 The Keccak/SHA-3 specifications can be found at:
376 <http://keccak.noekeon.org/Keccak-reference-3.0.pdf>
378 <http://keccak.noekeon.org/Keccak-submission-3.pdf>
379
381 Mark Shelor <mshelor@cpan.org>
382
384 The author is particularly grateful to
385 Guido Bertoni
387 Joan Daemen
388 Michael Peeters
389 Chris Skiscim
390 Gilles Van Assche
391 "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-2022 Mark Shelor
399 This library is free software; you can redistribute it and/or modify it
401 under the same terms as Perl itself.
402 perlartistic
404perl v5.36.0 2022-08-09 Digest::SHA3(3)