diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Digest::SHA.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Digest::SHA.3pm | 653 |
1 files changed, 653 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Digest::SHA.3pm b/upstream/mageia-cauldron/man3pm/Digest::SHA.3pm new file mode 100644 index 00000000..7cf26609 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Digest::SHA.3pm @@ -0,0 +1,653 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Digest::SHA 3pm" +.TH Digest::SHA 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Digest::SHA \- Perl extension for SHA\-1/224/256/384/512 +.SH SYNOPSIS +.IX Header "SYNOPSIS" +In programs: +.PP +.Vb 1 +\& # Functional interface +\& +\& use Digest::SHA qw(sha1 sha1_hex sha1_base64 ...); +\& +\& $digest = sha1($data); +\& $digest = sha1_hex($data); +\& $digest = sha1_base64($data); +\& +\& $digest = sha256($data); +\& $digest = sha384_hex($data); +\& $digest = sha512_base64($data); +\& +\& # Object\-oriented +\& +\& use Digest::SHA; +\& +\& $sha = Digest::SHA\->new($alg); +\& +\& $sha\->add($data); # feed data into stream +\& +\& $sha\->addfile(*F); +\& $sha\->addfile($filename); +\& +\& $sha\->add_bits($bits); +\& $sha\->add_bits($data, $nbits); +\& +\& $sha_copy = $sha\->clone; # make copy of digest object +\& $state = $sha\->getstate; # save current state to string +\& $sha\->putstate($state); # restore previous $state +\& +\& $digest = $sha\->digest; # compute digest +\& $digest = $sha\->hexdigest; +\& $digest = $sha\->b64digest; +.Ve +.PP +From the command line: +.PP +.Vb 1 +\& $ shasum files +\& +\& $ shasum \-\-help +.Ve +.SH "SYNOPSIS (HMAC-SHA)" +.IX Header "SYNOPSIS (HMAC-SHA)" +.Vb 1 +\& # Functional interface only +\& +\& use Digest::SHA qw(hmac_sha1 hmac_sha1_hex ...); +\& +\& $digest = hmac_sha1($data, $key); +\& $digest = hmac_sha224_hex($data, $key); +\& $digest = hmac_sha256_base64($data, $key); +.Ve +.SH ABSTRACT +.IX Header "ABSTRACT" +Digest::SHA is a complete implementation of the NIST Secure Hash Standard. +It gives Perl programmers a convenient way to calculate SHA\-1, SHA\-224, +SHA\-256, SHA\-384, SHA\-512, SHA\-512/224, and SHA\-512/256 message digests. +The module can handle all types of input, including partial-byte data. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +Digest::SHA is written in C for speed. If your platform lacks a +C compiler, you can install the functionally equivalent (but much +slower) Digest::SHA::PurePerl module. +.PP +The programming interface is easy to use: it's the same one found +in CPAN's Digest module. So, if your applications currently +use Digest::MD5 and you'd prefer the stronger security of SHA, +it's a simple matter to convert them. +.PP +The interface provides two ways to calculate digests: all-at-once, +or in stages. To illustrate, the following short program computes +the SHA\-256 digest of "hello world" using each approach: +.PP +.Vb 1 +\& use Digest::SHA qw(sha256_hex); +\& +\& $data = "hello world"; +\& @frags = split(//, $data); +\& +\& # all\-at\-once (Functional style) +\& $digest1 = sha256_hex($data); +\& +\& # in\-stages (OOP style) +\& $state = Digest::SHA\->new(256); +\& for (@frags) { $state\->add($_) } +\& $digest2 = $state\->hexdigest; +\& +\& print $digest1 eq $digest2 ? +\& "whew!\en" : "oops!\en"; +.Ve +.PP +To calculate the digest of an n\-bit message where \fIn\fR is not a +multiple of 8, use the \fR\f(BIadd_bits()\fR\fI\fR method. For example, consider +the 446\-bit message consisting of the bit-string "110" repeated +148 times, followed by "11". Here's how to display its SHA\-1 +digest: +.PP +.Vb 4 +\& use Digest::SHA; +\& $bits = "110" x 148 . "11"; +\& $sha = Digest::SHA\->new(1)\->add_bits($bits); +\& print $sha\->hexdigest, "\en"; +.Ve +.PP +Note that for larger bit-strings, it's more efficient to use the +two-argument version \fIadd_bits($data, \fR\f(CI$nbits\fR\fI)\fR, where \fR\f(CI$data\fR\fI\fR is +in the customary packed binary format used for Perl strings. +.PP +The module also lets you save intermediate SHA states to a string. The +\&\fR\f(BIgetstate()\fR\fI\fR method generates portable, human-readable text describing +the current state of computation. You can subsequently restore that +state with \fI\fR\f(BIputstate()\fR\fI\fR to resume where the calculation left off. +.PP +To see what a state description looks like, just run the following: +.PP +.Vb 2 +\& use Digest::SHA; +\& print Digest::SHA\->new\->add("Shaw" x 1962)\->getstate; +.Ve +.PP +As an added convenience, the Digest::SHA module offers routines to +calculate keyed hashes using the HMAC\-SHA\-1/224/256/384/512 +algorithms. These services exist in functional form only, and +mimic the style and behavior of the \fR\f(BIsha()\fR\fI\fR, \fI\fR\f(BIsha_hex()\fR\fI\fR, and +\&\fI\fR\f(BIsha_base64()\fR\fI\fR functions. +.PP +.Vb 1 +\& # Test vector from draft\-ietf\-ipsec\-ciph\-sha\-256\-01.txt +\& +\& use Digest::SHA qw(hmac_sha256_hex); +\& print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\en"; +.Ve +.SH "UNICODE AND SIDE EFFECTS" +.IX Header "UNICODE AND SIDE EFFECTS" +Perl supports Unicode strings as of version 5.6. Such strings may +contain wide characters, namely, characters whose ordinal values are +greater than 255. This can cause problems for digest algorithms such +as SHA that are specified to operate on sequences of bytes. +.PP +The rule by which Digest::SHA handles a Unicode string is easy +to state, but potentially confusing to grasp: the string is interpreted +as a sequence of byte values, where each byte value is equal to the +ordinal value (viz. code point) of its corresponding Unicode character. +That way, the Unicode string 'abc' has exactly the same digest value as +the ordinary string 'abc'. +.PP +Since a wide character does not fit into a byte, the Digest::SHA +routines croak if they encounter one. Whereas if a Unicode string +contains no wide characters, the module accepts it quite happily. +The following code illustrates the two cases: +.PP +.Vb 2 +\& $str1 = pack(\*(AqU*\*(Aq, (0..255)); +\& print sha1_hex($str1); # ok +\& +\& $str2 = pack(\*(AqU*\*(Aq, (0..256)); +\& print sha1_hex($str2); # croaks +.Ve +.PP +Be aware that the digest routines silently convert UTF\-8 input into its +equivalent byte sequence in the native encoding (cf. utf8::downgrade). +This side effect influences only the way Perl stores the data internally, +but otherwise leaves the actual value of the data intact. +.SH "NIST STATEMENT ON SHA\-1" +.IX Header "NIST STATEMENT ON SHA-1" +NIST acknowledges that the work of Prof. Xiaoyun Wang constitutes a +practical collision attack on SHA\-1. Therefore, NIST encourages the +rapid adoption of the SHA\-2 hash functions (e.g. SHA\-256) for applications +requiring strong collision resistance, such as digital signatures. +.PP +ref. <http://csrc.nist.gov/groups/ST/hash/statement.html> +.SH "PADDING OF BASE64 DIGESTS" +.IX Header "PADDING OF BASE64 DIGESTS" +By convention, CPAN Digest modules do \fBnot\fR pad their Base64 output. +Problems can occur when feeding such digests to other software that +expects properly padded Base64 encodings. +.PP +For the time being, any necessary padding must be done by the user. +Fortunately, this is a simple operation: if the length of a Base64\-encoded +digest isn't a multiple of 4, simply append "=" characters to the end +of the digest until it is: +.PP +.Vb 3 +\& while (length($b64_digest) % 4) { +\& $b64_digest .= \*(Aq=\*(Aq; +\& } +.Ve +.PP +To illustrate, \fIsha256_base64("abc")\fR is computed to be +.PP +.Vb 1 +\& ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0 +.Ve +.PP +which has a length of 43. So, the properly padded version is +.PP +.Vb 1 +\& ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0= +.Ve +.SH EXPORT +.IX Header "EXPORT" +None by default. +.SH "EXPORTABLE FUNCTIONS" +.IX Header "EXPORTABLE FUNCTIONS" +Provided your C compiler supports a 64\-bit type (e.g. the \fIlong +long\fR of C99, or \fI_\|_int64\fR used by Microsoft C/C++), all of these +functions will be available for use. Otherwise, you won't be able +to perform the SHA\-384 and SHA\-512 transforms, both of which require +64\-bit operations. +.PP +\&\fIFunctional style\fR +.IP "\fBsha1($data, ...)\fR" 4 +.IX Item "sha1($data, ...)" +.PD 0 +.IP "\fBsha224($data, ...)\fR" 4 +.IX Item "sha224($data, ...)" +.IP "\fBsha256($data, ...)\fR" 4 +.IX Item "sha256($data, ...)" +.IP "\fBsha384($data, ...)\fR" 4 +.IX Item "sha384($data, ...)" +.IP "\fBsha512($data, ...)\fR" 4 +.IX Item "sha512($data, ...)" +.IP "\fBsha512224($data, ...)\fR" 4 +.IX Item "sha512224($data, ...)" +.IP "\fBsha512256($data, ...)\fR" 4 +.IX Item "sha512256($data, ...)" +.PD +Logically joins the arguments into a single string, and returns +its SHA\-1/224/256/384/512 digest encoded as a binary string. +.IP "\fBsha1_hex($data, ...)\fR" 4 +.IX Item "sha1_hex($data, ...)" +.PD 0 +.IP "\fBsha224_hex($data, ...)\fR" 4 +.IX Item "sha224_hex($data, ...)" +.IP "\fBsha256_hex($data, ...)\fR" 4 +.IX Item "sha256_hex($data, ...)" +.IP "\fBsha384_hex($data, ...)\fR" 4 +.IX Item "sha384_hex($data, ...)" +.IP "\fBsha512_hex($data, ...)\fR" 4 +.IX Item "sha512_hex($data, ...)" +.IP "\fBsha512224_hex($data, ...)\fR" 4 +.IX Item "sha512224_hex($data, ...)" +.IP "\fBsha512256_hex($data, ...)\fR" 4 +.IX Item "sha512256_hex($data, ...)" +.PD +Logically joins the arguments into a single string, and returns +its SHA\-1/224/256/384/512 digest encoded as a hexadecimal string. +.IP "\fBsha1_base64($data, ...)\fR" 4 +.IX Item "sha1_base64($data, ...)" +.PD 0 +.IP "\fBsha224_base64($data, ...)\fR" 4 +.IX Item "sha224_base64($data, ...)" +.IP "\fBsha256_base64($data, ...)\fR" 4 +.IX Item "sha256_base64($data, ...)" +.IP "\fBsha384_base64($data, ...)\fR" 4 +.IX Item "sha384_base64($data, ...)" +.IP "\fBsha512_base64($data, ...)\fR" 4 +.IX Item "sha512_base64($data, ...)" +.IP "\fBsha512224_base64($data, ...)\fR" 4 +.IX Item "sha512224_base64($data, ...)" +.IP "\fBsha512256_base64($data, ...)\fR" 4 +.IX Item "sha512256_base64($data, ...)" +.PD +Logically joins the arguments into a single string, and returns +its SHA\-1/224/256/384/512 digest encoded as a Base64 string. +.Sp +It's important to note that the resulting string does \fBnot\fR contain +the padding characters typical of Base64 encodings. This omission is +deliberate, and is done to maintain compatibility with the family of +CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for details. +.PP +\&\fIOOP style\fR +.IP \fBnew($alg)\fR 4 +.IX Item "new($alg)" +Returns a new Digest::SHA object. Allowed values for \fR\f(CI$alg\fR\fI\fR are 1, +224, 256, 384, 512, 512224, or 512256. It's also possible to use +common string representations of the algorithm (e.g. "sha256", +"SHA\-384"). If the argument is missing, SHA\-1 will be used by +default. +.Sp +Invoking \fInew\fR as an instance method will reset the object to the +initial state associated with \fR\f(CI$alg\fR\fI\fR. If the argument is missing, +the object will continue using the same algorithm that was selected +at creation. +.IP \fBreset($alg)\fR 4 +.IX Item "reset($alg)" +This method has exactly the same effect as \fInew($alg)\fR. In fact, +\&\fIreset\fR is just an alias for \fInew\fR. +.IP \fBhashsize\fR 4 +.IX Item "hashsize" +Returns the number of digest bits for this object. The values are +160, 224, 256, 384, 512, 224, and 256 for SHA\-1, SHA\-224, SHA\-256, +SHA\-384, SHA\-512, SHA\-512/224 and SHA\-512/256, respectively. +.IP \fBalgorithm\fR 4 +.IX Item "algorithm" +Returns the digest algorithm for this object. The values are 1, +224, 256, 384, 512, 512224, and 512256 for SHA\-1, SHA\-224, SHA\-256, +SHA\-384, SHA\-512, SHA\-512/224, and SHA\-512/256, respectively. +.IP \fBclone\fR 4 +.IX Item "clone" +Returns a duplicate copy of the object. +.IP "\fBadd($data, ...)\fR" 4 +.IX Item "add($data, ...)" +Logically joins the arguments into a single string, and uses it to +update the current digest state. In other words, the following +statements have the same effect: +.Sp +.Vb 4 +\& $sha\->add("a"); $sha\->add("b"); $sha\->add("c"); +\& $sha\->add("a")\->add("b")\->add("c"); +\& $sha\->add("a", "b", "c"); +\& $sha\->add("abc"); +.Ve +.Sp +The return value is the updated object itself. +.ie n .IP "\fBadd_bits($data, \fR\fB$nbits\fR\fB)\fR" 4 +.el .IP "\fBadd_bits($data, \fR\f(CB$nbits\fR\fB)\fR" 4 +.IX Item "add_bits($data, $nbits)" +.PD 0 +.IP \fBadd_bits($bits)\fR 4 +.IX Item "add_bits($bits)" +.PD +Updates the current digest state by appending bits to it. The +return value is the updated object itself. +.Sp +The first form causes the most-significant \fR\f(CI$nbits\fR\fI\fR of \fI\fR\f(CI$data\fR\fI\fR +to be appended to the stream. The \fI\fR\f(CI$data\fR\fI\fR argument is in the +customary binary format used for Perl strings. +.Sp +The second form takes an ASCII string of "0" and "1" characters as +its argument. It's equivalent to +.Sp +.Vb 1 +\& $sha\->add_bits(pack("B*", $bits), length($bits)); +.Ve +.Sp +So, the following two statements do the same thing: +.Sp +.Vb 2 +\& $sha\->add_bits("111100001010"); +\& $sha\->add_bits("\exF0\exA0", 12); +.Ve +.Sp +Note that SHA\-1 and SHA\-2 use \fImost-significant-bit ordering\fR +for their internal state. This means that +.Sp +.Vb 1 +\& $sha3\->add_bits("110"); +.Ve +.Sp +is equivalent to +.Sp +.Vb 1 +\& $sha3\->add_bits("1")\->add_bits("1")\->add_bits("0"); +.Ve +.IP \fBaddfile(*FILE)\fR 4 +.IX Item "addfile(*FILE)" +Reads from \fIFILE\fR until EOF, and appends that data to the current +state. The return value is the updated object itself. +.ie n .IP "\fBaddfile($filename [, \fR\fB$mode\fR\fB])\fR" 4 +.el .IP "\fBaddfile($filename [, \fR\f(CB$mode\fR\fB])\fR" 4 +.IX Item "addfile($filename [, $mode])" +Reads the contents of \fR\f(CI$filename\fR\fI\fR, and appends that data to the current +state. The return value is the updated object itself. +.Sp +By default, \fR\f(CI$filename\fR\fI\fR is simply opened and read; no special modes +or I/O disciplines are used. To change this, set the optional \fI\fR\f(CI$mode\fR\fI\fR +argument to one of the following values: +.Sp +.Vb 1 +\& "b" read file in binary mode +\& +\& "U" use universal newlines +\& +\& "0" use BITS mode +.Ve +.Sp +The "U" mode is modeled on Python's "Universal Newlines" concept, whereby +DOS and Mac OS line terminators are converted internally to UNIX newlines +before processing. This ensures consistent digest values when working +simultaneously across multiple file systems. \fBThe "U" mode influences +only text files\fR, namely those passing Perl's \fI\-T\fR test; binary files +are processed with no translation whatsoever. +.Sp +The BITS mode ("0") interprets the contents of \fR\f(CI$filename\fR\fI\fR as a logical +stream of bits, where each ASCII '0' or '1' character represents a 0 or +1 bit, respectively. All other characters are ignored. This provides +a convenient way to calculate the digest values of partial-byte data +by using files, rather than having to write separate programs employing +the \fIadd_bits\fR method. +.IP \fBgetstate\fR 4 +.IX Item "getstate" +Returns a string containing a portable, human-readable representation +of the current SHA state. +.IP \fBputstate($str)\fR 4 +.IX Item "putstate($str)" +Returns a Digest::SHA object representing the SHA state contained +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 +produced by method \fIgetstate\fR. If called as a class method, a new +object is created; if called as an instance method, the object is reset +to the state contained in \fI\fR\f(CI$str\fR\fI\fR. +.IP \fBdump($filename)\fR 4 +.IX Item "dump($filename)" +Writes the output of \fIgetstate\fR to \fR\f(CI$filename\fR\fI\fR. If the argument is +missing, or equal to the empty string, the state information will be +written to STDOUT. +.IP \fBload($filename)\fR 4 +.IX Item "load($filename)" +Returns a Digest::SHA object that results from calling \fIputstate\fR on +the contents of \fR\f(CI$filename\fR\fI\fR. If the argument is missing, or equal to +the empty string, the state information will be read from STDIN. +.IP \fBdigest\fR 4 +.IX Item "digest" +Returns the digest encoded as a binary string. +.Sp +Note that the \fIdigest\fR method is a read-once operation. Once it +has been performed, the Digest::SHA object is automatically reset +in preparation for calculating another digest value. Call +\&\fR\f(CI$sha\fR\fI\->clone\->digest\fR if it's necessary to preserve the +original digest state. +.IP \fBhexdigest\fR 4 +.IX Item "hexdigest" +Returns the digest encoded as a hexadecimal string. +.Sp +Like \fIdigest\fR, this method is a read-once operation. Call +\&\fR\f(CI$sha\fR\fI\->clone\->hexdigest\fR if it's necessary to preserve +the original digest state. +.IP \fBb64digest\fR 4 +.IX Item "b64digest" +Returns the digest encoded as a Base64 string. +.Sp +Like \fIdigest\fR, this method is a read-once operation. Call +\&\fR\f(CI$sha\fR\fI\->clone\->b64digest\fR if it's necessary to preserve +the original digest state. +.Sp +It's important to note that the resulting string does \fBnot\fR contain +the padding characters typical of Base64 encodings. This omission is +deliberate, and is done to maintain compatibility with the family of +CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for details. +.PP +\&\fIHMAC\-SHA\-1/224/256/384/512\fR +.ie n .IP "\fBhmac_sha1($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha1($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha1($data, $key)" +.PD 0 +.ie n .IP "\fBhmac_sha224($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha224($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha224($data, $key)" +.ie n .IP "\fBhmac_sha256($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha256($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha256($data, $key)" +.ie n .IP "\fBhmac_sha384($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha384($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha384($data, $key)" +.ie n .IP "\fBhmac_sha512($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha512($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha512($data, $key)" +.ie n .IP "\fBhmac_sha512224($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha512224($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha512224($data, $key)" +.ie n .IP "\fBhmac_sha512256($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha512256($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha512256($data, $key)" +.PD +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, +with the result encoded as a binary string. Multiple \fI\fR\f(CI$data\fR\fI\fR +arguments are allowed, provided that \fI\fR\f(CI$key\fR\fI\fR is the last argument +in the list. +.ie n .IP "\fBhmac_sha1_hex($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha1_hex($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha1_hex($data, $key)" +.PD 0 +.ie n .IP "\fBhmac_sha224_hex($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha224_hex($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha224_hex($data, $key)" +.ie n .IP "\fBhmac_sha256_hex($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha256_hex($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha256_hex($data, $key)" +.ie n .IP "\fBhmac_sha384_hex($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha384_hex($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha384_hex($data, $key)" +.ie n .IP "\fBhmac_sha512_hex($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha512_hex($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha512_hex($data, $key)" +.ie n .IP "\fBhmac_sha512224_hex($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha512224_hex($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha512224_hex($data, $key)" +.ie n .IP "\fBhmac_sha512256_hex($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha512256_hex($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha512256_hex($data, $key)" +.PD +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, +with the result encoded as a hexadecimal string. Multiple \fI\fR\f(CI$data\fR\fI\fR +arguments are allowed, provided that \fI\fR\f(CI$key\fR\fI\fR is the last argument +in the list. +.ie n .IP "\fBhmac_sha1_base64($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha1_base64($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha1_base64($data, $key)" +.PD 0 +.ie n .IP "\fBhmac_sha224_base64($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha224_base64($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha224_base64($data, $key)" +.ie n .IP "\fBhmac_sha256_base64($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha256_base64($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha256_base64($data, $key)" +.ie n .IP "\fBhmac_sha384_base64($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha384_base64($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha384_base64($data, $key)" +.ie n .IP "\fBhmac_sha512_base64($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha512_base64($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha512_base64($data, $key)" +.ie n .IP "\fBhmac_sha512224_base64($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha512224_base64($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha512224_base64($data, $key)" +.ie n .IP "\fBhmac_sha512256_base64($data, \fR\fB$key\fR\fB)\fR" 4 +.el .IP "\fBhmac_sha512256_base64($data, \fR\f(CB$key\fR\fB)\fR" 4 +.IX Item "hmac_sha512256_base64($data, $key)" +.PD +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, +with the result encoded as a Base64 string. Multiple \fI\fR\f(CI$data\fR\fI\fR +arguments are allowed, provided that \fI\fR\f(CI$key\fR\fI\fR is the last argument +in the list. +.Sp +It's important to note that the resulting string does \fBnot\fR contain +the padding characters typical of Base64 encodings. This omission is +deliberate, and is done to maintain compatibility with the family of +CPAN Digest modules. See "PADDING OF BASE64 DIGESTS" for details. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Digest, Digest::SHA::PurePerl +.PP +The Secure Hash Standard (Draft FIPS PUB 180\-4) can be found at: +.PP +<http://csrc.nist.gov/publications/drafts/fips180\-4/Draft\-FIPS180\-4_Feb2011.pdf> +.PP +The Keyed-Hash Message Authentication Code (HMAC): +.PP +<http://csrc.nist.gov/publications/fips/fips198/fips\-198a.pdf> +.SH AUTHOR +.IX Header "AUTHOR" +.Vb 1 +\& Mark Shelor <mshelor@cpan.org> +.Ve +.SH ACKNOWLEDGMENTS +.IX Header "ACKNOWLEDGMENTS" +The author is particularly grateful to +.PP +.Vb 10 +\& Gisle Aas +\& H. Merijn Brand +\& Sean Burke +\& Chris Carey +\& Alexandr Ciornii +\& Chris David +\& Jim Doble +\& Thomas Drugeon +\& Julius Duque +\& Jeffrey Friedl +\& Robert Gilmour +\& Brian Gladman +\& Jarkko Hietaniemi +\& Adam Kennedy +\& Mark Lawrence +\& Andy Lester +\& Alex Muntada +\& Steve Peters +\& Chris Skiscim +\& Martin Thurn +\& Gunnar Wolf +\& Adam Woodbury +.Ve +.PP +"who by trained skill rescued life from such great billows and such thick +darkness and moored it in so perfect a calm and in so brilliant a light" +\&\- Lucretius +.SH "COPYRIGHT AND LICENSE" +.IX Header "COPYRIGHT AND LICENSE" +Copyright (C) 2003\-2022 Mark Shelor +.PP +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. +.PP +perlartistic |