local-lib5/man/man3/Digest::SHA.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Digest::SHA 3"
 127 .TH Digest::SHA 3 "2010-01-04" "perl v5.8.8" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Digest::SHA \- Perl extension for SHA\-1/224/256/384/512
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 In programs:
 137 .PP
 138 .Vb 1
 139 \&                # Functional interface
 140 \&
 141 \&        use Digest::SHA qw(sha1 sha1_hex sha1_base64 ...);
 142 \&
 143 \&        $digest = sha1($data);
 144 \&        $digest = sha1_hex($data);
 145 \&        $digest = sha1_base64($data);
 146 \&
 147 \&        $digest = sha256($data);
 148 \&        $digest = sha384_hex($data);
 149 \&        $digest = sha512_base64($data);
 150 \&
 151 \&                # Object\-oriented
 152 \&
 153 \&        use Digest::SHA;
 154 \&
 155 \&        $sha = Digest::SHA\->new($alg);
 156 \&
 157 \&        $sha\->add($data);               # feed data into stream
 158 \&
 159 \&        $sha\->addfile(*F);
 160 \&        $sha\->addfile($filename);
 161 \&
 162 \&        $sha\->add_bits($bits);
 163 \&        $sha\->add_bits($data, $nbits);
 164 \&
 165 \&        $sha_copy = $sha\->clone;        # if needed, make copy of
 166 \&        $sha\->dump($file);              #       current digest state,
 167 \&        $sha\->load($file);              #       or save it on disk
 168 \&
 169 \&        $digest = $sha\->digest;         # compute digest
 170 \&        $digest = $sha\->hexdigest;
 171 \&        $digest = $sha\->b64digest;
 172 .Ve
 173 .PP
 174 From the command line:
 175 .PP
 176 .Vb 1
 177 \&        $ shasum files
 178 \&
 179 \&        $ shasum \-\-help
 180 .Ve
 181 .SH "SYNOPSIS (HMAC-SHA)"
 182 .IX Header "SYNOPSIS (HMAC-SHA)"
 183 .Vb 1
 184 \&                # Functional interface only
 185 \&
 186 \&        use Digest::SHA qw(hmac_sha1 hmac_sha1_hex ...);
 187 \&
 188 \&        $digest = hmac_sha1($data, $key);
 189 \&        $digest = hmac_sha224_hex($data, $key);
 190 \&        $digest = hmac_sha256_base64($data, $key);
 191 .Ve
 192 .SH "ABSTRACT"
 193 .IX Header "ABSTRACT"
 194 Digest::SHA is a complete implementation of the \s-1NIST\s0 Secure Hash
 195 Standard.  It gives Perl programmers a convenient way to calculate
 196 \&\s-1SHA\-1\s0, \s-1SHA\-224\s0, \s-1SHA\-256\s0, \s-1SHA\-384\s0, and \s-1SHA\-512\s0 message digests.
 197 The module can handle all types of input, including partial-byte
 198 data.
 199 .SH "DESCRIPTION"
 200 .IX Header "DESCRIPTION"
 201 Digest::SHA is written in C for speed.  If your platform lacks a
 202 C compiler, you can install the functionally equivalent (but much
 203 slower) Digest::SHA::PurePerl module.
 204 .PP
 205 The programming interface is easy to use: it's the same one found
 206 in \s-1CPAN\s0's Digest module.  So, if your applications currently
 207 use Digest::MD5 and you'd prefer the stronger security of \s-1SHA\s0,
 208 it's a simple matter to convert them.
 209 .PP
 210 The interface provides two ways to calculate digests:  all-at-once,
 211 or in stages.  To illustrate, the following short program computes
 212 the \s-1SHA\-256\s0 digest of \*(L"hello world\*(R" using each approach:
 213 .PP
 214 .Vb 1
 215 \&        use Digest::SHA qw(sha256_hex);
 216 \&
 217 \&        $data = "hello world";
 218 \&        @frags = split(//, $data);
 219 \&
 220 \&        # all\-at\-once (Functional style)
 221 \&        $digest1 = sha256_hex($data);
 222 \&
 223 \&        # in\-stages (OOP style)
 224 \&        $state = Digest::SHA\->new(256);
 225 \&        for (@frags) { $state\->add($_) }
 226 \&        $digest2 = $state\->hexdigest;
 227 \&
 228 \&        print $digest1 eq $digest2 ?
 229 \&                "whew!\en" : "oops!\en";
 230 .Ve
 231 .PP
 232 To calculate the digest of an n\-bit message where \fIn\fR is not a
 233 multiple of 8, use the \fI\fIadd_bits()\fI\fR method.  For example, consider
 234 the 446\-bit message consisting of the bit-string \*(L"110\*(R" repeated
 235 148 times, followed by \*(L"11\*(R".  Here's how to display its \s-1SHA\-1\s0
 236 digest:
 237 .PP
 238 .Vb 4
 239 \&        use Digest::SHA;
 240 \&        $bits = "110" x 148 . "11";
 241 \&        $sha = Digest::SHA\->new(1)\->add_bits($bits);
 242 \&        print $sha\->hexdigest, "\en";
 243 .Ve
 244 .PP
 245 Note that for larger bit-strings, it's more efficient to use the
 246 two-argument version \fIadd_bits($data, \f(CI$nbits\fI)\fR, where \fI\f(CI$data\fI\fR is
 247 in the customary packed binary format used for Perl strings.
 248 .PP
 249 The module also lets you save intermediate \s-1SHA\s0 states to disk, or
 250 display them on standard output.  The \fI\fIdump()\fI\fR method generates
 251 portable, human-readable text describing the current state of
 252 computation.  You can subsequently retrieve the file with \fI\fIload()\fI\fR
 253 to resume where the calculation left off.
 254 .PP
 255 To see what a state description looks like, just run the following:
 256 .PP
 257 .Vb 2
 258 \&        use Digest::SHA;
 259 \&        Digest::SHA\->new\->add("Shaw" x 1962)\->dump;
 260 .Ve
 261 .PP
 262 As an added convenience, the Digest::SHA module offers routines to
 263 calculate keyed hashes using the \s-1HMAC\-SHA\-1/224/256/384/512\s0
 264 algorithms.  These services exist in functional form only, and
 265 mimic the style and behavior of the \fI\fIsha()\fI\fR, \fI\fIsha_hex()\fI\fR, and
 266 \&\fI\fIsha_base64()\fI\fR functions.
 267 .PP
 268 .Vb 1
 269 \&        # Test vector from draft\-ietf\-ipsec\-ciph\-sha\-256\-01.txt
 270 \&
 271 \&        use Digest::SHA qw(hmac_sha256_hex);
 272 \&        print hmac_sha256_hex("Hi There", chr(0x0b) x 32), "\en";
 273 .Ve
 274 .SH "NIST STATEMENT ON SHA\-1"
 275 .IX Header "NIST STATEMENT ON SHA-1"
 276 \&\fI\s-1NIST\s0 was recently informed that researchers had discovered a way
 277 to \*(L"break\*(R" the current Federal Information Processing Standard \s-1SHA\-1\s0
 278 algorithm, which has been in effect since 1994. The researchers
 279 have not yet published their complete results, so \s-1NIST\s0 has not
 280 confirmed these findings. However, the researchers are a reputable
 281 research team with expertise in this area.\fR
 282 .PP
 283 \&\fIDue to advances in computing power, \s-1NIST\s0 already planned to phase
 284 out \s-1SHA\-1\s0 in favor of the larger and stronger hash functions (\s-1SHA\-224\s0,
 285 \&\s-1SHA\-256\s0, \s-1SHA\-384\s0 and \s-1SHA\-512\s0) by 2010. New developments should use
 286 the larger and stronger hash functions.\fR
 287 .PP
 288 ref. <http://www.csrc.nist.gov/pki/HashWorkshop/NIST%20Statement/Burr_Mar2005.html>
 289 .SH "PADDING OF BASE64 DIGESTS"
 290 .IX Header "PADDING OF BASE64 DIGESTS"
 291 By convention, \s-1CPAN\s0 Digest modules do \fBnot\fR pad their Base64 output.
 292 Problems can occur when feeding such digests to other software that
 293 expects properly padded Base64 encodings.
 294 .PP
 295 For the time being, any necessary padding must be done by the user.
 296 Fortunately, this is a simple operation: if the length of a Base64\-encoded
 297 digest isn't a multiple of 4, simply append \*(L"=\*(R" characters to the end
 298 of the digest until it is:
 299 .PP
 300 .Vb 3
 301 \&        while (length($b64_digest) % 4) {
 302 \&                $b64_digest .= \*(Aq=\*(Aq;
 303 \&        }
 304 .Ve
 305 .PP
 306 To illustrate, \fIsha256_base64(\*(L"abc\*(R")\fR is computed to be
 307 .PP
 308 .Vb 1
 309 \&        ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0
 310 .Ve
 311 .PP
 312 which has a length of 43.  So, the properly padded version is
 313 .PP
 314 .Vb 1
 315 \&        ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=
 316 .Ve
 317 .SH "EXPORT"
 318 .IX Header "EXPORT"
 319 None by default.
 320 .SH "EXPORTABLE FUNCTIONS"
 321 .IX Header "EXPORTABLE FUNCTIONS"
 322 Provided your C compiler supports a 64\-bit type (e.g. the \fIlong
 323 long\fR of C99, or \fI_\|_int64\fR used by Microsoft C/\*(C+), all of these
 324 functions will be available for use.  Otherwise, you won't be able
 325 to perform the \s-1SHA\-384\s0 and \s-1SHA\-512\s0 transforms, both of which require
 326 64\-bit operations.
 327 .PP
 328 \&\fIFunctional style\fR
 329 .IP "\fBsha1($data, ...)\fR" 4
 330 .IX Item "sha1($data, ...)"
 331 .PD 0
 332 .IP "\fBsha224($data, ...)\fR" 4
 333 .IX Item "sha224($data, ...)"
 334 .IP "\fBsha256($data, ...)\fR" 4
 335 .IX Item "sha256($data, ...)"
 336 .IP "\fBsha384($data, ...)\fR" 4
 337 .IX Item "sha384($data, ...)"
 338 .IP "\fBsha512($data, ...)\fR" 4
 339 .IX Item "sha512($data, ...)"
 340 .PD
 341 Logically joins the arguments into a single string, and returns
 342 its \s-1SHA\-1/224/256/384/512\s0 digest encoded as a binary string.
 343 .IP "\fBsha1_hex($data, ...)\fR" 4
 344 .IX Item "sha1_hex($data, ...)"
 345 .PD 0
 346 .IP "\fBsha224_hex($data, ...)\fR" 4
 347 .IX Item "sha224_hex($data, ...)"
 348 .IP "\fBsha256_hex($data, ...)\fR" 4
 349 .IX Item "sha256_hex($data, ...)"
 350 .IP "\fBsha384_hex($data, ...)\fR" 4
 351 .IX Item "sha384_hex($data, ...)"
 352 .IP "\fBsha512_hex($data, ...)\fR" 4
 353 .IX Item "sha512_hex($data, ...)"
 354 .PD
 355 Logically joins the arguments into a single string, and returns
 356 its \s-1SHA\-1/224/256/384/512\s0 digest encoded as a hexadecimal string.
 357 .IP "\fBsha1_base64($data, ...)\fR" 4
 358 .IX Item "sha1_base64($data, ...)"
 359 .PD 0
 360 .IP "\fBsha224_base64($data, ...)\fR" 4
 361 .IX Item "sha224_base64($data, ...)"
 362 .IP "\fBsha256_base64($data, ...)\fR" 4
 363 .IX Item "sha256_base64($data, ...)"
 364 .IP "\fBsha384_base64($data, ...)\fR" 4
 365 .IX Item "sha384_base64($data, ...)"
 366 .IP "\fBsha512_base64($data, ...)\fR" 4
 367 .IX Item "sha512_base64($data, ...)"
 368 .PD
 369 Logically joins the arguments into a single string, and returns
 370 its \s-1SHA\-1/224/256/384/512\s0 digest encoded as a Base64 string.
 371 .Sp
 372 It's important to note that the resulting string does \fBnot\fR contain
 373 the padding characters typical of Base64 encodings.  This omission is
 374 deliberate, and is done to maintain compatibility with the family of
 375 \&\s-1CPAN\s0 Digest modules.  See \*(L"\s-1PADDING\s0 \s-1OF\s0 \s-1BASE64\s0 \s-1DIGESTS\s0\*(R" for details.
 376 .PP
 377 \&\fI\s-1OOP\s0 style\fR
 378 .IP "\fBnew($alg)\fR" 4
 379 .IX Item "new($alg)"
 380 Returns a new Digest::SHA object.  Allowed values for \fI\f(CI$alg\fI\fR are
 381 1, 224, 256, 384, or 512.  It's also possible to use common string
 382 representations of the algorithm (e.g. \*(L"sha256\*(R", \*(L"\s-1SHA\-384\s0\*(R").  If
 383 the argument is missing, \s-1SHA\-1\s0 will be used by default.
 384 .Sp
 385 Invoking \fInew\fR as an instance method will not create a new object;
 386 instead, it will simply reset the object to the initial state
 387 associated with \fI\f(CI$alg\fI\fR.  If the argument is missing, the object
 388 will continue using the same algorithm that was selected at creation.
 389 .IP "\fBreset($alg)\fR" 4
 390 .IX Item "reset($alg)"
 391 This method has exactly the same effect as \fInew($alg)\fR.  In fact,
 392 \&\fIreset\fR is just an alias for \fInew\fR.
 393 .IP "\fBhashsize\fR" 4
 394 .IX Item "hashsize"
 395 Returns the number of digest bits for this object.  The values are
 396 160, 224, 256, 384, and 512 for \s-1SHA\-1\s0, \s-1SHA\-224\s0, \s-1SHA\-256\s0, \s-1SHA\-384\s0,
 397 and \s-1SHA\-512\s0, respectively.
 398 .IP "\fBalgorithm\fR" 4
 399 .IX Item "algorithm"
 400 Returns the digest algorithm for this object.  The values are 1,
 401 224, 256, 384, and 512 for \s-1SHA\-1\s0, \s-1SHA\-224\s0, \s-1SHA\-256\s0, \s-1SHA\-384\s0, and
 402 \&\s-1SHA\-512\s0, respectively.
 403 .IP "\fBclone\fR" 4
 404 .IX Item "clone"
 405 Returns a duplicate copy of the object.
 406 .IP "\fBadd($data, ...)\fR" 4
 407 .IX Item "add($data, ...)"
 408 Logically joins the arguments into a single string, and uses it to
 409 update the current digest state.  In other words, the following
 410 statements have the same effect:
 411 .Sp
 412 .Vb 4
 413 \&        $sha\->add("a"); $sha\->add("b"); $sha\->add("c");
 414 \&        $sha\->add("a")\->add("b")\->add("c");
 415 \&        $sha\->add("a", "b", "c");
 416 \&        $sha\->add("abc");
 417 .Ve
 418 .Sp
 419 The return value is the updated object itself.
 420 .ie n .IP "\fBadd_bits($data, \fB$nbits\fB)\fR" 4
 421 .el .IP "\fBadd_bits($data, \f(CB$nbits\fB)\fR" 4
 422 .IX Item "add_bits($data, $nbits)"
 423 .PD 0
 424 .IP "\fBadd_bits($bits)\fR" 4
 425 .IX Item "add_bits($bits)"
 426 .PD
 427 Updates the current digest state by appending bits to it.  The
 428 return value is the updated object itself.
 429 .Sp
 430 The first form causes the most-significant \fI\f(CI$nbits\fI\fR of \fI\f(CI$data\fI\fR
 431 to be appended to the stream.  The \fI\f(CI$data\fI\fR argument is in the
 432 customary binary format used for Perl strings.
 433 .Sp
 434 The second form takes an \s-1ASCII\s0 string of \*(L"0\*(R" and \*(L"1\*(R" characters as
 435 its argument.  It's equivalent to
 436 .Sp
 437 .Vb 1
 438 \&        $sha\->add_bits(pack("B*", $bits), length($bits));
 439 .Ve
 440 .Sp
 441 So, the following two statements do the same thing:
 442 .Sp
 443 .Vb 2
 444 \&        $sha\->add_bits("111100001010");
 445 \&        $sha\->add_bits("\exF0\exA0", 12);
 446 .Ve
 447 .IP "\fBaddfile(*FILE)\fR" 4
 448 .IX Item "addfile(*FILE)"
 449 Reads from \fI\s-1FILE\s0\fR until \s-1EOF\s0, and appends that data to the current
 450 state.  The return value is the updated object itself.
 451 .ie n .IP "\fBaddfile($filename [, \fB$mode\fB])\fR" 4
 452 .el .IP "\fBaddfile($filename [, \f(CB$mode\fB])\fR" 4
 453 .IX Item "addfile($filename [, $mode])"
 454 Reads the contents of \fI\f(CI$filename\fI\fR, and appends that data to the current
 455 state.  The return value is the updated object itself.
 456 .Sp
 457 By default, \fI\f(CI$filename\fI\fR is simply opened and read; no special modes
 458 or I/O disciplines are used.  To change this, set the optional \fI\f(CI$mode\fI\fR
 459 argument to one of the following values:
 460 .Sp
 461 .Vb 1
 462 \&        "b"     read file in binary mode
 463 \&
 464 \&        "p"     use portable mode
 465 .Ve
 466 .Sp
 467 The \*(L"p\*(R" mode is handy since it ensures that the digest value of
 468 \&\fI\f(CI$filename\fI\fR will be the same when computed on different operating
 469 systems.  It accomplishes this by internally translating all newlines in
 470 text files to \s-1UNIX\s0 format before calculating the digest.  Binary files
 471 are read in raw mode with no translation whatsoever.
 472 .Sp
 473 For a fuller discussion of newline formats, refer to \s-1CPAN\s0 module
 474 File::LocalizeNewlines.  Its \*(L"universal line separator\*(R" regex forms
 475 the basis of \fIaddfile\fR's portable mode processing.
 476 .IP "\fBdump($filename)\fR" 4
 477 .IX Item "dump($filename)"
 478 Provides persistent storage of intermediate \s-1SHA\s0 states by writing
 479 a portable, human-readable representation of the current state to
 480 \&\fI\f(CI$filename\fI\fR.  If the argument is missing, or equal to the empty
 481 string, the state information will be written to \s-1STDOUT\s0.
 482 .IP "\fBload($filename)\fR" 4
 483 .IX Item "load($filename)"
 484 Returns a Digest::SHA object representing the intermediate \s-1SHA\s0
 485 state that was previously dumped to \fI\f(CI$filename\fI\fR.  If called as a
 486 class method, a new object is created; if called as an instance
 487 method, the object is reset to the state contained in \fI\f(CI$filename\fI\fR.
 488 If the argument is missing, or equal to the empty string, the state
 489 information will be read from \s-1STDIN\s0.
 490 .IP "\fBdigest\fR" 4
 491 .IX Item "digest"
 492 Returns the digest encoded as a binary string.
 493 .Sp
 494 Note that the \fIdigest\fR method is a read-once operation. Once it
 495 has been performed, the Digest::SHA object is automatically reset
 496 in preparation for calculating another digest value.  Call
 497 \&\fI\f(CI$sha\fI\->clone\->digest\fR if it's necessary to preserve the
 498 original digest state.
 499 .IP "\fBhexdigest\fR" 4
 500 .IX Item "hexdigest"
 501 Returns the digest encoded as a hexadecimal string.
 502 .Sp
 503 Like \fIdigest\fR, this method is a read-once operation.  Call
 504 \&\fI\f(CI$sha\fI\->clone\->hexdigest\fR if it's necessary to preserve
 505 the original digest state.
 506 .Sp
 507 This method is inherited if Digest::base is installed on your
 508 system.  Otherwise, a functionally equivalent substitute is used.
 509 .IP "\fBb64digest\fR" 4
 510 .IX Item "b64digest"
 511 Returns the digest encoded as a Base64 string.
 512 .Sp
 513 Like \fIdigest\fR, this method is a read-once operation.  Call
 514 \&\fI\f(CI$sha\fI\->clone\->b64digest\fR if it's necessary to preserve
 515 the original digest state.
 516 .Sp
 517 This method is inherited if Digest::base is installed on your
 518 system.  Otherwise, a functionally equivalent substitute is used.
 519 .Sp
 520 It's important to note that the resulting string does \fBnot\fR contain
 521 the padding characters typical of Base64 encodings.  This omission is
 522 deliberate, and is done to maintain compatibility with the family of
 523 \&\s-1CPAN\s0 Digest modules.  See \*(L"\s-1PADDING\s0 \s-1OF\s0 \s-1BASE64\s0 \s-1DIGESTS\s0\*(R" for details.
 524 .PP
 525 \&\fI\s-1HMAC\-SHA\-1/224/256/384/512\s0\fR
 526 .ie n .IP "\fBhmac_sha1($data, \fB$key\fB)\fR" 4
 527 .el .IP "\fBhmac_sha1($data, \f(CB$key\fB)\fR" 4
 528 .IX Item "hmac_sha1($data, $key)"
 529 .PD 0
 530 .ie n .IP "\fBhmac_sha224($data, \fB$key\fB)\fR" 4
 531 .el .IP "\fBhmac_sha224($data, \f(CB$key\fB)\fR" 4
 532 .IX Item "hmac_sha224($data, $key)"
 533 .ie n .IP "\fBhmac_sha256($data, \fB$key\fB)\fR" 4
 534 .el .IP "\fBhmac_sha256($data, \f(CB$key\fB)\fR" 4
 535 .IX Item "hmac_sha256($data, $key)"
 536 .ie n .IP "\fBhmac_sha384($data, \fB$key\fB)\fR" 4
 537 .el .IP "\fBhmac_sha384($data, \f(CB$key\fB)\fR" 4
 538 .IX Item "hmac_sha384($data, $key)"
 539 .ie n .IP "\fBhmac_sha512($data, \fB$key\fB)\fR" 4
 540 .el .IP "\fBhmac_sha512($data, \f(CB$key\fB)\fR" 4
 541 .IX Item "hmac_sha512($data, $key)"
 542 .PD
 543 Returns the \s-1HMAC\-SHA\-1/224/256/384/512\s0 digest of \fI\f(CI$data\fI\fR/\fI\f(CI$key\fI\fR,
 544 with the result encoded as a binary string.  Multiple \fI\f(CI$data\fI\fR
 545 arguments are allowed, provided that \fI\f(CI$key\fI\fR is the last argument
 546 in the list.
 547 .ie n .IP "\fBhmac_sha1_hex($data, \fB$key\fB)\fR" 4
 548 .el .IP "\fBhmac_sha1_hex($data, \f(CB$key\fB)\fR" 4
 549 .IX Item "hmac_sha1_hex($data, $key)"
 550 .PD 0
 551 .ie n .IP "\fBhmac_sha224_hex($data, \fB$key\fB)\fR" 4
 552 .el .IP "\fBhmac_sha224_hex($data, \f(CB$key\fB)\fR" 4
 553 .IX Item "hmac_sha224_hex($data, $key)"
 554 .ie n .IP "\fBhmac_sha256_hex($data, \fB$key\fB)\fR" 4
 555 .el .IP "\fBhmac_sha256_hex($data, \f(CB$key\fB)\fR" 4
 556 .IX Item "hmac_sha256_hex($data, $key)"
 557 .ie n .IP "\fBhmac_sha384_hex($data, \fB$key\fB)\fR" 4
 558 .el .IP "\fBhmac_sha384_hex($data, \f(CB$key\fB)\fR" 4
 559 .IX Item "hmac_sha384_hex($data, $key)"
 560 .ie n .IP "\fBhmac_sha512_hex($data, \fB$key\fB)\fR" 4
 561 .el .IP "\fBhmac_sha512_hex($data, \f(CB$key\fB)\fR" 4
 562 .IX Item "hmac_sha512_hex($data, $key)"
 563 .PD
 564 Returns the \s-1HMAC\-SHA\-1/224/256/384/512\s0 digest of \fI\f(CI$data\fI\fR/\fI\f(CI$key\fI\fR,
 565 with the result encoded as a hexadecimal string.  Multiple \fI\f(CI$data\fI\fR
 566 arguments are allowed, provided that \fI\f(CI$key\fI\fR is the last argument
 567 in the list.
 568 .ie n .IP "\fBhmac_sha1_base64($data, \fB$key\fB)\fR" 4
 569 .el .IP "\fBhmac_sha1_base64($data, \f(CB$key\fB)\fR" 4
 570 .IX Item "hmac_sha1_base64($data, $key)"
 571 .PD 0
 572 .ie n .IP "\fBhmac_sha224_base64($data, \fB$key\fB)\fR" 4
 573 .el .IP "\fBhmac_sha224_base64($data, \f(CB$key\fB)\fR" 4
 574 .IX Item "hmac_sha224_base64($data, $key)"
 575 .ie n .IP "\fBhmac_sha256_base64($data, \fB$key\fB)\fR" 4
 576 .el .IP "\fBhmac_sha256_base64($data, \f(CB$key\fB)\fR" 4
 577 .IX Item "hmac_sha256_base64($data, $key)"
 578 .ie n .IP "\fBhmac_sha384_base64($data, \fB$key\fB)\fR" 4
 579 .el .IP "\fBhmac_sha384_base64($data, \f(CB$key\fB)\fR" 4
 580 .IX Item "hmac_sha384_base64($data, $key)"
 581 .ie n .IP "\fBhmac_sha512_base64($data, \fB$key\fB)\fR" 4
 582 .el .IP "\fBhmac_sha512_base64($data, \f(CB$key\fB)\fR" 4
 583 .IX Item "hmac_sha512_base64($data, $key)"
 584 .PD
 585 Returns the \s-1HMAC\-SHA\-1/224/256/384/512\s0 digest of \fI\f(CI$data\fI\fR/\fI\f(CI$key\fI\fR,
 586 with the result encoded as a Base64 string.  Multiple \fI\f(CI$data\fI\fR
 587 arguments are allowed, provided that \fI\f(CI$key\fI\fR is the last argument
 588 in the list.
 589 .Sp
 590 It's important to note that the resulting string does \fBnot\fR contain
 591 the padding characters typical of Base64 encodings.  This omission is
 592 deliberate, and is done to maintain compatibility with the family of
 593 \&\s-1CPAN\s0 Digest modules.  See \*(L"\s-1PADDING\s0 \s-1OF\s0 \s-1BASE64\s0 \s-1DIGESTS\s0\*(R" for details.
 594 .SH "SEE ALSO"
 595 .IX Header "SEE ALSO"
 596 Digest, Digest::SHA::PurePerl
 597 .PP
 598 The Secure Hash Standard (\s-1FIPS\s0 \s-1PUB\s0 180\-2) can be found at:
 599 .PP
 600 <http://csrc.nist.gov/publications/fips/fips180\-2/fips180\-2withchangenotice.pdf>
 601 .PP
 602 The Keyed-Hash Message Authentication Code (\s-1HMAC\s0):
 603 .PP
 604 <http://csrc.nist.gov/publications/fips/fips198/fips\-198a.pdf>
 605 .SH "AUTHOR"
 606 .IX Header "AUTHOR"
 607 .Vb 1
 608 \&        Mark Shelor     <mshelor@cpan.org>
 609 .Ve
 610 .SH "ACKNOWLEDGMENTS"
 611 .IX Header "ACKNOWLEDGMENTS"
 612 The author is particularly grateful to
 613 .PP
 614 .Vb 10
 615 \&        Gisle Aas
 616 \&        Chris Carey
 617 \&        Alexandr Ciornii
 618 \&        Jim Doble
 619 \&        Julius Duque
 620 \&        Jeffrey Friedl
 621 \&        Robert Gilmour
 622 \&        Brian Gladman
 623 \&        Adam Kennedy
 624 \&        Andy Lester
 625 \&        Alex Muntada
 626 \&        Steve Peters
 627 \&        Chris Skiscim
 628 \&        Martin Thurn
 629 \&        Gunnar Wolf
 630 \&        Adam Woodbury
 631 .Ve
 632 .PP
 633 for their valuable comments and suggestions.
 634 .SH "COPYRIGHT AND LICENSE"
 635 .IX Header "COPYRIGHT AND LICENSE"
 636 Copyright (C) 2003\-2010 Mark Shelor
 637 .PP
 638 This library is free software; you can redistribute it and/or modify
 639 it under the same terms as Perl itself.
 640 .PP
 641 perlartistic