Debian Codegraph @

upstream/mageia-cauldron/man3pm/Digest::SHA.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Digest::SHA 3pm"
61 .TH Digest::SHA 3pm 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Digest::SHA \- Perl extension for SHA\-1/224/256/384/512
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 In programs:
71 .PP
72 .Vb 1
73 \& # Functional interface
74 \&
75 \& use Digest::SHA qw(sha1 sha1_hex sha1_base64 ...);
76 \&
77 \& $digest = sha1($data);
78 \& $digest = sha1_hex($data);
79 \& $digest = sha1_base64($data);
80 \&
81 \& $digest = sha256($data);
82 \& $digest = sha384_hex($data);
83 \& $digest = sha512_base64($data);
84 \&
85 \& # Object\-oriented
86 \&
87 \& use Digest::SHA;
88 \&
89 \& $sha = Digest::SHA\->new($alg);
90 \&
91 \& $sha\->add($data); # feed data into stream
92 \&
93 \& $sha\->addfile(*F);
94 \& $sha\->addfile($filename);
95 \&
96 \& $sha\->add_bits($bits);
97 \& $sha\->add_bits($data, $nbits);
98 \&
99 \& $sha_copy = $sha\->clone; # make copy of digest object
100 \& $state = $sha\->getstate; # save current state to string
101 \& $sha\->putstate($state); # restore previous $state
102 \&
103 \& $digest = $sha\->digest; # compute digest
104 \& $digest = $sha\->hexdigest;
105 \& $digest = $sha\->b64digest;
106 .Ve
107 .PP
108 From the command line:
109 .PP
110 .Vb 1
111 \& $ shasum files
112 \&
113 \& $ shasum \-\-help
114 .Ve
115 .SH "SYNOPSIS (HMAC\-SHA)"
116 .IX Header "SYNOPSIS (HMAC-SHA)"
117 .Vb 1
118 \& # Functional interface only
119 \&
120 \& use Digest::SHA qw(hmac_sha1 hmac_sha1_hex ...);
121 \&
122 \& $digest = hmac_sha1($data, $key);
123 \& $digest = hmac_sha224_hex($data, $key);
124 \& $digest = hmac_sha256_base64($data, $key);
125 .Ve
126 .SH ABSTRACT
127 .IX Header "ABSTRACT"
128 Digest::SHA is a complete implementation of the NIST Secure Hash Standard.
129 It gives Perl programmers a convenient way to calculate SHA\-1, SHA\-224,
130 SHA\-256, SHA\-384, SHA\-512, SHA\-512/224, and SHA\-512/256 message digests.
131 The module can handle all types of input, including partial\-byte data.
132 .SH DESCRIPTION
133 .IX Header "DESCRIPTION"
134 Digest::SHA is written in C for speed. If your platform lacks a
135 C compiler, you can install the functionally equivalent (but much
136 slower) Digest::SHA::PurePerl module.
137 .PP
138 The programming interface is easy to use: it\*(Aqs the same one found
139 in CPAN\*(Aqs Digest module. So, if your applications currently
140 use Digest::MD5 and you\*(Aqd prefer the stronger security of SHA,
141 it\*(Aqs a simple matter to convert them.
142 .PP
143 The interface provides two ways to calculate digests: all\-at\-once,
144 or in stages. To illustrate, the following short program computes
145 the SHA\-256 digest of "hello world" using each approach:
146 .PP
147 .Vb 1
148 \& use Digest::SHA qw(sha256_hex);
149 \&
150 \& $data = "hello world";
151 \& @frags = split(//, $data);
152 \&
153 \& # all\-at\-once (Functional style)
154 \& $digest1 = sha256_hex($data);
155 \&
156 \& # in\-stages (OOP style)
157 \& $state = Digest::SHA\->new(256);
158 \& for (@frags) { $state\->add($_) }
159 \& $digest2 = $state\->hexdigest;
160 \&
161 \& print $digest1 eq $digest2 ?
162 \& "whew!\en" : "oops!\en";
163 .Ve
164 .PP
165 To calculate the digest of an n\-bit message where \fIn\fR is not a
166 multiple of 8, use the \fR\f(BIadd_bits()\fR\fI\fR method. For example, consider
167 the 446\-bit message consisting of the bit\-string "110" repeated
168 148 times, followed by "11". Here\*(Aqs how to display its SHA\-1
169 digest:
170 .PP
171 .Vb 4
172 \& use Digest::SHA;
173 \& $bits = "110" x 148 . "11";
174 \& $sha = Digest::SHA\->new(1)\->add_bits($bits);
175 \& print $sha\->hexdigest, "\en";
176 .Ve
177 .PP
178 Note that for larger bit\-strings, it\*(Aqs more efficient to use the
179 two\-argument version \fIadd_bits($data, \fR\f(CI$nbits\fR\fI)\fR, where \fR\f(CI$data\fR\fI\fR is
180 in the customary packed binary format used for Perl strings.
181 .PP
182 The module also lets you save intermediate SHA states to a string. The
183 \&\fR\f(BIgetstate()\fR\fI\fR method generates portable, human\-readable text describing
184 the current state of computation. You can subsequently restore that
185 state with \fI\fR\f(BIputstate()\fR\fI\fR to resume where the calculation left off.
186 .PP
187 To see what a state description looks like, just run the following:
188 .PP
189 .Vb 2
190 \& use Digest::SHA;
191 \& print Digest::SHA\->new\->add("Shaw" x 1962)\->getstate;
192 .Ve
193 .PP
194 As an added convenience, the Digest::SHA module offers routines to
195 calculate keyed hashes using the HMAC\-SHA\-1/224/256/384/512
196 algorithms. These services exist in functional form only, and
197 mimic the style and behavior of the \fR\f(BIsha()\fR\fI\fR, \fI\fR\f(BIsha_hex()\fR\fI\fR, and
198 \&\fI\fR\f(BIsha_base64()\fR\fI\fR functions.
199 .PP
200 .Vb 1
201 \& # Test vector from draft\-ietf\-ipsec\-ciph\-sha\-256\-01.txt
202 \&
203 \& use Digest::SHA qw(hmac_sha256_hex);
204 \& print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\en";
205 .Ve
206 .SH "UNICODE AND SIDE EFFECTS"
207 .IX Header "UNICODE AND SIDE EFFECTS"
208 Perl supports Unicode strings as of version 5.6. Such strings may
209 contain wide characters, namely, characters whose ordinal values are
210 greater than 255. This can cause problems for digest algorithms such
211 as SHA that are specified to operate on sequences of bytes.
212 .PP
213 The rule by which Digest::SHA handles a Unicode string is easy
214 to state, but potentially confusing to grasp: the string is interpreted
215 as a sequence of byte values, where each byte value is equal to the
216 ordinal value (viz. code point) of its corresponding Unicode character.
217 That way, the Unicode string \*(Aqabc\*(Aq has exactly the same digest value as
218 the ordinary string \*(Aqabc\*(Aq.
219 .PP
220 Since a wide character does not fit into a byte, the Digest::SHA
221 routines croak if they encounter one. Whereas if a Unicode string
222 contains no wide characters, the module accepts it quite happily.
223 The following code illustrates the two cases:
224 .PP
225 .Vb 2
226 \& $str1 = pack(\*(AqU*\*(Aq, (0..255));
227 \& print sha1_hex($str1); # ok
228 \&
229 \& $str2 = pack(\*(AqU*\*(Aq, (0..256));
230 \& print sha1_hex($str2); # croaks
231 .Ve
232 .PP
233 Be aware that the digest routines silently convert UTF\-8 input into its
234 equivalent byte sequence in the native encoding (cf. utf8::downgrade).
235 This side effect influences only the way Perl stores the data internally,
236 but otherwise leaves the actual value of the data intact.
237 .SH "NIST STATEMENT ON SHA\-1"
238 .IX Header "NIST STATEMENT ON SHA-1"
239 NIST acknowledges that the work of Prof. Xiaoyun Wang constitutes a
240 practical collision attack on SHA\-1. Therefore, NIST encourages the
241 rapid adoption of the SHA\-2 hash functions (e.g. SHA\-256) for applications
242 requiring strong collision resistance, such as digital signatures.
243 .PP
244 ref. <http://csrc.nist.gov/groups/ST/hash/statement.html>
245 .SH "PADDING OF BASE64 DIGESTS"
246 .IX Header "PADDING OF BASE64 DIGESTS"
247 By convention, CPAN Digest modules do \fBnot\fR pad their Base64 output.
248 Problems can occur when feeding such digests to other software that
249 expects properly padded Base64 encodings.
250 .PP
251 For the time being, any necessary padding must be done by the user.
252 Fortunately, this is a simple operation: if the length of a Base64\-encoded
253 digest isn\*(Aqt a multiple of 4, simply append "=" characters to the end
254 of the digest until it is:
255 .PP
256 .Vb 3
257 \& while (length($b64_digest) % 4) {
258 \& $b64_digest .= \*(Aq=\*(Aq;
259 \& }
260 .Ve
261 .PP
262 To illustrate, \fIsha256_base64("abc")\fR is computed to be
263 .PP
264 .Vb 1
265 \& ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0
266 .Ve
267 .PP
268 which has a length of 43. So, the properly padded version is
269 .PP
270 .Vb 1
271 \& ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
272 .Ve
273 .SH EXPORT
274 .IX Header "EXPORT"
275 None by default.
276 .SH "EXPORTABLE FUNCTIONS"
277 .IX Header "EXPORTABLE FUNCTIONS"
278 Provided your C compiler supports a 64\-bit type (e.g. the \fIlong
279 long\fR of C99, or \fI_\|_int64\fR used by Microsoft C/C++), all of these
280 functions will be available for use. Otherwise, you won\*(Aqt be able
281 to perform the SHA\-384 and SHA\-512 transforms, both of which require
282 64\-bit operations.
283 .PP
284 \&\fIFunctional style\fR
285 .IP "\fBsha1($data, ...)\fR" 4
286 .IX Item "sha1($data, ...)"
287 .PD 0
288 .IP "\fBsha224($data, ...)\fR" 4
289 .IX Item "sha224($data, ...)"
290 .IP "\fBsha256($data, ...)\fR" 4
291 .IX Item "sha256($data, ...)"
292 .IP "\fBsha384($data, ...)\fR" 4
293 .IX Item "sha384($data, ...)"
294 .IP "\fBsha512($data, ...)\fR" 4
295 .IX Item "sha512($data, ...)"
296 .IP "\fBsha512224($data, ...)\fR" 4
297 .IX Item "sha512224($data, ...)"
298 .IP "\fBsha512256($data, ...)\fR" 4
299 .IX Item "sha512256($data, ...)"
300 .PD
301 Logically joins the arguments into a single string, and returns
302 its SHA\-1/224/256/384/512 digest encoded as a binary string.
303 .IP "\fBsha1_hex($data, ...)\fR" 4
304 .IX Item "sha1_hex($data, ...)"
305 .PD 0
306 .IP "\fBsha224_hex($data, ...)\fR" 4
307 .IX Item "sha224_hex($data, ...)"
308 .IP "\fBsha256_hex($data, ...)\fR" 4
309 .IX Item "sha256_hex($data, ...)"
310 .IP "\fBsha384_hex($data, ...)\fR" 4
311 .IX Item "sha384_hex($data, ...)"
312 .IP "\fBsha512_hex($data, ...)\fR" 4
313 .IX Item "sha512_hex($data, ...)"
314 .IP "\fBsha512224_hex($data, ...)\fR" 4
315 .IX Item "sha512224_hex($data, ...)"
316 .IP "\fBsha512256_hex($data, ...)\fR" 4
317 .IX Item "sha512256_hex($data, ...)"
318 .PD
319 Logically joins the arguments into a single string, and returns
320 its SHA\-1/224/256/384/512 digest encoded as a hexadecimal string.
321 .IP "\fBsha1_base64($data, ...)\fR" 4
322 .IX Item "sha1_base64($data, ...)"
323 .PD 0
324 .IP "\fBsha224_base64($data, ...)\fR" 4
325 .IX Item "sha224_base64($data, ...)"
326 .IP "\fBsha256_base64($data, ...)\fR" 4
327 .IX Item "sha256_base64($data, ...)"
328 .IP "\fBsha384_base64($data, ...)\fR" 4
329 .IX Item "sha384_base64($data, ...)"
330 .IP "\fBsha512_base64($data, ...)\fR" 4
331 .IX Item "sha512_base64($data, ...)"
332 .IP "\fBsha512224_base64($data, ...)\fR" 4
333 .IX Item "sha512224_base64($data, ...)"
334 .IP "\fBsha512256_base64($data, ...)\fR" 4
335 .IX Item "sha512256_base64($data, ...)"
336 .PD
337 Logically joins the arguments into a single string, and returns
338 its SHA\-1/224/256/384/512 digest encoded as a Base64 string.
339 .Sp
340 It\*(Aqs important to note that the resulting string does \fBnot\fR contain
341 the padding characters typical of Base64 encodings. This omission is
342 deliberate, and is done to maintain compatibility with the family of
343 CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for details.
344 .PP
345 \&\fIOOP style\fR
346 .IP \fBnew($alg)\fR 4
347 .IX Item "new($alg)"
348 Returns a new Digest::SHA object. Allowed values for \fR\f(CI$alg\fR\fI\fR are 1,
349 224, 256, 384, 512, 512224, or 512256. It\*(Aqs also possible to use
350 common string representations of the algorithm (e.g. "sha256",
351 "SHA\-384"). If the argument is missing, SHA\-1 will be used by
352 default.
353 .Sp
354 Invoking \fInew\fR as an instance method will reset the object to the
355 initial state associated with \fR\f(CI$alg\fR\fI\fR. If the argument is missing,
356 the object will continue using the same algorithm that was selected
357 at creation.
358 .IP \fBreset($alg)\fR 4
359 .IX Item "reset($alg)"
360 This method has exactly the same effect as \fInew($alg)\fR. In fact,
361 \&\fIreset\fR is just an alias for \fInew\fR.
362 .IP \fBhashsize\fR 4
363 .IX Item "hashsize"
364 Returns the number of digest bits for this object. The values are
365 160, 224, 256, 384, 512, 224, and 256 for SHA\-1, SHA\-224, SHA\-256,
366 SHA\-384, SHA\-512, SHA\-512/224 and SHA\-512/256, respectively.
367 .IP \fBalgorithm\fR 4
368 .IX Item "algorithm"
369 Returns the digest algorithm for this object. The values are 1,
370 224, 256, 384, 512, 512224, and 512256 for SHA\-1, SHA\-224, SHA\-256,
371 SHA\-384, SHA\-512, SHA\-512/224, and SHA\-512/256, respectively.
372 .IP \fBclone\fR 4
373 .IX Item "clone"
374 Returns a duplicate copy of the object.
375 .IP "\fBadd($data, ...)\fR" 4
376 .IX Item "add($data, ...)"
377 Logically joins the arguments into a single string, and uses it to
378 update the current digest state. In other words, the following
379 statements have the same effect:
380 .Sp
381 .Vb 4
382 \& $sha\->add("a"); $sha\->add("b"); $sha\->add("c");
383 \& $sha\->add("a")\->add("b")\->add("c");
384 \& $sha\->add("a", "b", "c");
385 \& $sha\->add("abc");
386 .Ve
387 .Sp
388 The return value is the updated object itself.
389 .ie n .IP "\fBadd_bits($data, \fR\fB$nbits\fR\fB)\fR" 4
390 .el .IP "\fBadd_bits($data, \fR\f(CB$nbits\fR\fB)\fR" 4
391 .IX Item "add_bits($data, $nbits)"
392 .PD 0
393 .IP \fBadd_bits($bits)\fR 4
394 .IX Item "add_bits($bits)"
395 .PD
396 Updates the current digest state by appending bits to it. The
397 return value is the updated object itself.
398 .Sp
399 The first form causes the most\-significant \fR\f(CI$nbits\fR\fI\fR of \fI\fR\f(CI$data\fR\fI\fR
400 to be appended to the stream. The \fI\fR\f(CI$data\fR\fI\fR argument is in the
401 customary binary format used for Perl strings.
402 .Sp
403 The second form takes an ASCII string of "0" and "1" characters as
404 its argument. It\*(Aqs equivalent to
405 .Sp
406 .Vb 1
407 \& $sha\->add_bits(pack("B*", $bits), length($bits));
408 .Ve
409 .Sp
410 So, the following two statements do the same thing:
411 .Sp
412 .Vb 2
413 \& $sha\->add_bits("111100001010");
414 \& $sha\->add_bits("\exF0\exA0", 12);
415 .Ve
416 .Sp
417 Note that SHA\-1 and SHA\-2 use \fImost\-significant\-bit ordering\fR
418 for their internal state. This means that
419 .Sp
420 .Vb 1
421 \& $sha3\->add_bits("110");
422 .Ve
423 .Sp
424 is equivalent to
425 .Sp
426 .Vb 1
427 \& $sha3\->add_bits("1")\->add_bits("1")\->add_bits("0");
428 .Ve
429 .IP \fBaddfile(*FILE)\fR 4
430 .IX Item "addfile(*FILE)"
431 Reads from \fIFILE\fR until EOF, and appends that data to the current
432 state. The return value is the updated object itself.
433 .ie n .IP "\fBaddfile($filename [, \fR\fB$mode\fR\fB])\fR" 4
434 .el .IP "\fBaddfile($filename [, \fR\f(CB$mode\fR\fB])\fR" 4
435 .IX Item "addfile($filename [, $mode])"
436 Reads the contents of \fR\f(CI$filename\fR\fI\fR, and appends that data to the current
437 state. The return value is the updated object itself.
438 .Sp
439 By default, \fR\f(CI$filename\fR\fI\fR is simply opened and read; no special modes
440 or I/O disciplines are used. To change this, set the optional \fI\fR\f(CI$mode\fR\fI\fR
441 argument to one of the following values:
442 .Sp
443 .Vb 1
444 \& "b" read file in binary mode
445 \&
446 \& "U" use universal newlines
447 \&
448 \& "0" use BITS mode
449 .Ve
450 .Sp
451 The "U" mode is modeled on Python\*(Aqs "Universal Newlines" concept, whereby
452 DOS and Mac OS line terminators are converted internally to UNIX newlines
453 before processing. This ensures consistent digest values when working
454 simultaneously across multiple file systems. \fBThe "U" mode influences
455 only text files\fR, namely those passing Perl\*(Aqs \fI\-T\fR test; binary files
456 are processed with no translation whatsoever.
457 .Sp
458 The BITS mode ("0") interprets the contents of \fR\f(CI$filename\fR\fI\fR as a logical
459 stream of bits, where each ASCII \*(Aq0\*(Aq or \*(Aq1\*(Aq character represents a 0 or
460 1 bit, respectively. All other characters are ignored. This provides
461 a convenient way to calculate the digest values of partial\-byte data
462 by using files, rather than having to write separate programs employing
463 the \fIadd_bits\fR method.
464 .IP \fBgetstate\fR 4
465 .IX Item "getstate"
466 Returns a string containing a portable, human\-readable representation
467 of the current SHA state.
468 .IP \fBputstate($str)\fR 4
469 .IX Item "putstate($str)"
470 Returns a Digest::SHA object representing the SHA state contained
471 in \fR\f(CI$str\fR\fI\fR. The format of \fI\fR\f(CI$str\fR\fI\fR matches the format of the output
472 produced by method \fIgetstate\fR. If called as a class method, a new
473 object is created; if called as an instance method, the object is reset
474 to the state contained in \fI\fR\f(CI$str\fR\fI\fR.
475 .IP \fBdump($filename)\fR 4
476 .IX Item "dump($filename)"
477 Writes the output of \fIgetstate\fR to \fR\f(CI$filename\fR\fI\fR. If the argument is
478 missing, or equal to the empty string, the state information will be
479 written to STDOUT.
480 .IP \fBload($filename)\fR 4
481 .IX Item "load($filename)"
482 Returns a Digest::SHA object that results from calling \fIputstate\fR on
483 the contents of \fR\f(CI$filename\fR\fI\fR. If the argument is missing, or equal to
484 the empty string, the state information will be read from STDIN.
485 .IP \fBdigest\fR 4
486 .IX Item "digest"
487 Returns the digest encoded as a binary string.
488 .Sp
489 Note that the \fIdigest\fR method is a read\-once operation. Once it
490 has been performed, the Digest::SHA object is automatically reset
491 in preparation for calculating another digest value. Call
492 \&\fR\f(CI$sha\fR\fI\->clone\->digest\fR if it\*(Aqs necessary to preserve the
493 original digest state.
494 .IP \fBhexdigest\fR 4
495 .IX Item "hexdigest"
496 Returns the digest encoded as a hexadecimal string.
497 .Sp
498 Like \fIdigest\fR, this method is a read\-once operation. Call
499 \&\fR\f(CI$sha\fR\fI\->clone\->hexdigest\fR if it\*(Aqs necessary to preserve
500 the original digest state.
501 .IP \fBb64digest\fR 4
502 .IX Item "b64digest"
503 Returns the digest encoded as a Base64 string.
504 .Sp
505 Like \fIdigest\fR, this method is a read\-once operation. Call
506 \&\fR\f(CI$sha\fR\fI\->clone\->b64digest\fR if it\*(Aqs necessary to preserve
507 the original digest state.
508 .Sp
509 It\*(Aqs important to note that the resulting string does \fBnot\fR contain
510 the padding characters typical of Base64 encodings. This omission is
511 deliberate, and is done to maintain compatibility with the family of
512 CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for details.
513 .PP
514 \&\fIHMAC\-SHA\-1/224/256/384/512\fR
515 .ie n .IP "\fBhmac_sha1($data, \fR\fB$key\fR\fB)\fR" 4
516 .el .IP "\fBhmac_sha1($data, \fR\f(CB$key\fR\fB)\fR" 4
517 .IX Item "hmac_sha1($data, $key)"
518 .PD 0
519 .ie n .IP "\fBhmac_sha224($data, \fR\fB$key\fR\fB)\fR" 4
520 .el .IP "\fBhmac_sha224($data, \fR\f(CB$key\fR\fB)\fR" 4
521 .IX Item "hmac_sha224($data, $key)"
522 .ie n .IP "\fBhmac_sha256($data, \fR\fB$key\fR\fB)\fR" 4
523 .el .IP "\fBhmac_sha256($data, \fR\f(CB$key\fR\fB)\fR" 4
524 .IX Item "hmac_sha256($data, $key)"
525 .ie n .IP "\fBhmac_sha384($data, \fR\fB$key\fR\fB)\fR" 4
526 .el .IP "\fBhmac_sha384($data, \fR\f(CB$key\fR\fB)\fR" 4
527 .IX Item "hmac_sha384($data, $key)"
528 .ie n .IP "\fBhmac_sha512($data, \fR\fB$key\fR\fB)\fR" 4
529 .el .IP "\fBhmac_sha512($data, \fR\f(CB$key\fR\fB)\fR" 4
530 .IX Item "hmac_sha512($data, $key)"
531 .ie n .IP "\fBhmac_sha512224($data, \fR\fB$key\fR\fB)\fR" 4
532 .el .IP "\fBhmac_sha512224($data, \fR\f(CB$key\fR\fB)\fR" 4
533 .IX Item "hmac_sha512224($data, $key)"
534 .ie n .IP "\fBhmac_sha512256($data, \fR\fB$key\fR\fB)\fR" 4
535 .el .IP "\fBhmac_sha512256($data, \fR\f(CB$key\fR\fB)\fR" 4
536 .IX Item "hmac_sha512256($data, $key)"
537 .PD
538 Returns the HMAC\-SHA\-1/224/256/384/512 digest of \fR\f(CI$data\fR\fI\fR/\fI\fR\f(CI$key\fR\fI\fR,
539 with the result encoded as a binary string. Multiple \fI\fR\f(CI$data\fR\fI\fR
540 arguments are allowed, provided that \fI\fR\f(CI$key\fR\fI\fR is the last argument
541 in the list.
542 .ie n .IP "\fBhmac_sha1_hex($data, \fR\fB$key\fR\fB)\fR" 4
543 .el .IP "\fBhmac_sha1_hex($data, \fR\f(CB$key\fR\fB)\fR" 4
544 .IX Item "hmac_sha1_hex($data, $key)"
545 .PD 0
546 .ie n .IP "\fBhmac_sha224_hex($data, \fR\fB$key\fR\fB)\fR" 4
547 .el .IP "\fBhmac_sha224_hex($data, \fR\f(CB$key\fR\fB)\fR" 4
548 .IX Item "hmac_sha224_hex($data, $key)"
549 .ie n .IP "\fBhmac_sha256_hex($data, \fR\fB$key\fR\fB)\fR" 4
550 .el .IP "\fBhmac_sha256_hex($data, \fR\f(CB$key\fR\fB)\fR" 4
551 .IX Item "hmac_sha256_hex($data, $key)"
552 .ie n .IP "\fBhmac_sha384_hex($data, \fR\fB$key\fR\fB)\fR" 4
553 .el .IP "\fBhmac_sha384_hex($data, \fR\f(CB$key\fR\fB)\fR" 4
554 .IX Item "hmac_sha384_hex($data, $key)"
555 .ie n .IP "\fBhmac_sha512_hex($data, \fR\fB$key\fR\fB)\fR" 4
556 .el .IP "\fBhmac_sha512_hex($data, \fR\f(CB$key\fR\fB)\fR" 4
557 .IX Item "hmac_sha512_hex($data, $key)"
558 .ie n .IP "\fBhmac_sha512224_hex($data, \fR\fB$key\fR\fB)\fR" 4
559 .el .IP "\fBhmac_sha512224_hex($data, \fR\f(CB$key\fR\fB)\fR" 4
560 .IX Item "hmac_sha512224_hex($data, $key)"
561 .ie n .IP "\fBhmac_sha512256_hex($data, \fR\fB$key\fR\fB)\fR" 4
562 .el .IP "\fBhmac_sha512256_hex($data, \fR\f(CB$key\fR\fB)\fR" 4
563 .IX Item "hmac_sha512256_hex($data, $key)"
564 .PD
565 Returns the HMAC\-SHA\-1/224/256/384/512 digest of \fR\f(CI$data\fR\fI\fR/\fI\fR\f(CI$key\fR\fI\fR,
566 with the result encoded as a hexadecimal string. Multiple \fI\fR\f(CI$data\fR\fI\fR
567 arguments are allowed, provided that \fI\fR\f(CI$key\fR\fI\fR is the last argument
568 in the list.
569 .ie n .IP "\fBhmac_sha1_base64($data, \fR\fB$key\fR\fB)\fR" 4
570 .el .IP "\fBhmac_sha1_base64($data, \fR\f(CB$key\fR\fB)\fR" 4
571 .IX Item "hmac_sha1_base64($data, $key)"
572 .PD 0
573 .ie n .IP "\fBhmac_sha224_base64($data, \fR\fB$key\fR\fB)\fR" 4
574 .el .IP "\fBhmac_sha224_base64($data, \fR\f(CB$key\fR\fB)\fR" 4
575 .IX Item "hmac_sha224_base64($data, $key)"
576 .ie n .IP "\fBhmac_sha256_base64($data, \fR\fB$key\fR\fB)\fR" 4
577 .el .IP "\fBhmac_sha256_base64($data, \fR\f(CB$key\fR\fB)\fR" 4
578 .IX Item "hmac_sha256_base64($data, $key)"
579 .ie n .IP "\fBhmac_sha384_base64($data, \fR\fB$key\fR\fB)\fR" 4
580 .el .IP "\fBhmac_sha384_base64($data, \fR\f(CB$key\fR\fB)\fR" 4
581 .IX Item "hmac_sha384_base64($data, $key)"
582 .ie n .IP "\fBhmac_sha512_base64($data, \fR\fB$key\fR\fB)\fR" 4
583 .el .IP "\fBhmac_sha512_base64($data, \fR\f(CB$key\fR\fB)\fR" 4
584 .IX Item "hmac_sha512_base64($data, $key)"
585 .ie n .IP "\fBhmac_sha512224_base64($data, \fR\fB$key\fR\fB)\fR" 4
586 .el .IP "\fBhmac_sha512224_base64($data, \fR\f(CB$key\fR\fB)\fR" 4
587 .IX Item "hmac_sha512224_base64($data, $key)"
588 .ie n .IP "\fBhmac_sha512256_base64($data, \fR\fB$key\fR\fB)\fR" 4
589 .el .IP "\fBhmac_sha512256_base64($data, \fR\f(CB$key\fR\fB)\fR" 4
590 .IX Item "hmac_sha512256_base64($data, $key)"
591 .PD
592 Returns the HMAC\-SHA\-1/224/256/384/512 digest of \fR\f(CI$data\fR\fI\fR/\fI\fR\f(CI$key\fR\fI\fR,
593 with the result encoded as a Base64 string. Multiple \fI\fR\f(CI$data\fR\fI\fR
594 arguments are allowed, provided that \fI\fR\f(CI$key\fR\fI\fR is the last argument
595 in the list.
596 .Sp
597 It\*(Aqs important to note that the resulting string does \fBnot\fR contain
598 the padding characters typical of Base64 encodings. This omission is
599 deliberate, and is done to maintain compatibility with the family of
600 CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for details.
601 .SH "SEE ALSO"
602 .IX Header "SEE ALSO"
603 Digest, Digest::SHA::PurePerl
604 .PP
605 The Secure Hash Standard (Draft FIPS PUB 180\-4) can be found at:
606 .PP
607 <http://csrc.nist.gov/publications/drafts/fips180\-4/Draft\-FIPS180\-4_Feb2011.pdf>
608 .PP
609 The Keyed\-Hash Message Authentication Code (HMAC):
610 .PP
611 <http://csrc.nist.gov/publications/fips/fips198/fips\-198a.pdf>
612 .SH AUTHOR
613 .IX Header "AUTHOR"
614 .Vb 1
615 \& Mark Shelor <[email protected]>
616 .Ve
617 .SH ACKNOWLEDGMENTS
618 .IX Header "ACKNOWLEDGMENTS"
619 The author is particularly grateful to
620 .PP
621 .Vb 10
622 \& Gisle Aas
623 \& H. Merijn Brand
624 \& Sean Burke
625 \& Chris Carey
626 \& Alexandr Ciornii
627 \& Chris David
628 \& Jim Doble
629 \& Thomas Drugeon
630 \& Julius Duque
631 \& Jeffrey Friedl
632 \& Robert Gilmour
633 \& Brian Gladman
634 \& Jarkko Hietaniemi
635 \& Adam Kennedy
636 \& Mark Lawrence
637 \& Andy Lester
638 \& Alex Muntada
639 \& Steve Peters
640 \& Chris Skiscim
641 \& Martin Thurn
642 \& Gunnar Wolf
643 \& Adam Woodbury
644 .Ve
645 .PP
646 "who by trained skill rescued life from such great billows and such thick
647 darkness and moored it in so perfect a calm and in so brilliant a light"
648 \&\- Lucretius
649 .SH "COPYRIGHT AND LICENSE"
650 .IX Header "COPYRIGHT AND LICENSE"
651 Copyright (C) 2003\-2022 Mark Shelor
652 .PP
653 This library is free software; you can redistribute it and/or modify
654 it under the same terms as Perl itself.
655 .PP
656 perlartistic