Debian Codegraph @

upstream/debian-unstable/man3/Digest::SHA.3perl

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