local-lib5/man/man3/Digest::SHA1.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 "SHA1 3"
 127 .TH SHA1 3 "2009-05-23" "perl v5.8.7" "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::SHA1 \- Perl interface to the SHA\-1 algorithm
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 2
 137 \& # Functional style
 138 \& use Digest::SHA1  qw(sha1 sha1_hex sha1_base64);
 139 \&
 140 \& $digest = sha1($data);
 141 \& $digest = sha1_hex($data);
 142 \& $digest = sha1_base64($data);
 143 \& $digest = sha1_transform($data);
 144 \&
 145 \&
 146 \& # OO style
 147 \& use Digest::SHA1;
 148 \&
 149 \& $sha1 = Digest::SHA1\->new;
 150 \&
 151 \& $sha1\->add($data);
 152 \& $sha1\->addfile(*FILE);
 153 \&
 154 \& $sha1_copy = $sha1\->clone;
 155 \&
 156 \& $digest = $sha1\->digest;
 157 \& $digest = $sha1\->hexdigest;
 158 \& $digest = $sha1\->b64digest;
 159 \& $digest = $sha1\->transform;
 160 .Ve
 161 .SH "DESCRIPTION"
 162 .IX Header "DESCRIPTION"
 163 The \f(CW\*(C`Digest::SHA1\*(C'\fR module allows you to use the \s-1NIST\s0 \s-1SHA\-1\s0 message
 164 digest algorithm from within Perl programs.  The algorithm takes as
 165 input a message of arbitrary length and produces as output a 160\-bit
 166 \&\*(L"fingerprint\*(R" or \*(L"message digest\*(R" of the input.
 167 .PP
 168 In 2005, security flaws were identified in \s-1SHA\-1\s0, namely that a possible
 169 mathematical weakness might exist, indicating that a stronger hash function
 170 would be desirable.  The Digest::SHA module implements the stronger
 171 algorithms in the \s-1SHA\s0 family.
 172 .PP
 173 The \f(CW\*(C`Digest::SHA1\*(C'\fR module provide a procedural interface for simple
 174 use, as well as an object oriented interface that can handle messages
 175 of arbitrary length and which can read files directly.
 176 .SH "FUNCTIONS"
 177 .IX Header "FUNCTIONS"
 178 The following functions can be exported from the \f(CW\*(C`Digest::SHA1\*(C'\fR
 179 module.  No functions are exported by default.
 180 .IP "sha1($data,...)" 4
 181 .IX Item "sha1($data,...)"
 182 This function will concatenate all arguments, calculate the \s-1SHA\-1\s0
 183 digest of this \*(L"message\*(R", and return it in binary form.  The returned
 184 string will be 20 bytes long.
 185 .Sp
 186 The result of sha1(\*(L"a\*(R", \*(L"b\*(R", \*(L"c\*(R") will be exactly the same as the
 187 result of sha1(\*(L"abc\*(R").
 188 .IP "sha1_hex($data,...)" 4
 189 .IX Item "sha1_hex($data,...)"
 190 Same as \fIsha1()\fR, but will return the digest in hexadecimal form.  The
 191 length of the returned string will be 40 and it will only contain
 192 characters from this set: '0'..'9' and 'a'..'f'.
 193 .IP "sha1_base64($data,...)" 4
 194 .IX Item "sha1_base64($data,...)"
 195 Same as \fIsha1()\fR, but will return the digest as a base64 encoded string.
 196 The length of the returned string will be 27 and it will only contain
 197 characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and
 198 \&'/'.
 199 .Sp
 200 Note that the base64 encoded string returned is not padded to be a
 201 multiple of 4 bytes long.  If you want interoperability with other
 202 base64 encoded sha1 digests you might want to append the redundant
 203 string \*(L"=\*(R" to the result.
 204 .IP "sha1_transform($data)" 4
 205 .IX Item "sha1_transform($data)"
 206 Implements the basic \s-1SHA1\s0 transform on a 64 byte block. The \f(CW$data\fR
 207 argument and the returned \f(CW$digest\fR are in binary form. This algorithm
 208 is used in \s-1NIST\s0 \s-1FIPS\s0 186\-2
 209 .SH "METHODS"
 210 .IX Header "METHODS"
 211 The object oriented interface to \f(CW\*(C`Digest::SHA1\*(C'\fR is described in this
 212 section.  After a \f(CW\*(C`Digest::SHA1\*(C'\fR object has been created, you will add
 213 data to it and finally ask for the digest in a suitable format.  A
 214 single object can be used to calculate multiple digests.
 215 .PP
 216 The following methods are provided:
 217 .ie n .IP "$sha1 = Digest::SHA1\->new" 4
 218 .el .IP "\f(CW$sha1\fR = Digest::SHA1\->new" 4
 219 .IX Item "$sha1 = Digest::SHA1->new"
 220 The constructor returns a new \f(CW\*(C`Digest::SHA1\*(C'\fR object which encapsulate
 221 the state of the \s-1SHA\-1\s0 message-digest algorithm.
 222 .Sp
 223 If called as an instance method (i.e. \f(CW$sha1\fR\->new) it will just reset the
 224 state the object to the state of a newly created object.  No new
 225 object is created in this case.
 226 .ie n .IP "$sha1\->reset" 4
 227 .el .IP "\f(CW$sha1\fR\->reset" 4
 228 .IX Item "$sha1->reset"
 229 This is just an alias for \f(CW$sha1\fR\->new.
 230 .ie n .IP "$sha1\->clone" 4
 231 .el .IP "\f(CW$sha1\fR\->clone" 4
 232 .IX Item "$sha1->clone"
 233 This a copy of the \f(CW$sha1\fR object. It is useful when you do not want to
 234 destroy the digests state, but need an intermediate value of the
 235 digest, e.g. when calculating digests iteratively on a continuous data
 236 stream.  Example:
 237 .Sp
 238 .Vb 5
 239 \&    my $sha1 = Digest::SHA1\->new;
 240 \&    while (<>) {
 241 \&        $sha1\->add($_);
 242 \&        print "Line $.: ", $sha1\->clone\->hexdigest, "\en";
 243 \&    }
 244 .Ve
 245 .ie n .IP "$sha1\->add($data,...)" 4
 246 .el .IP "\f(CW$sha1\fR\->add($data,...)" 4
 247 .IX Item "$sha1->add($data,...)"
 248 The \f(CW$data\fR provided as argument are appended to the message we
 249 calculate the digest for.  The return value is the \f(CW$sha1\fR object itself.
 250 .Sp
 251 All these lines will have the same effect on the state of the \f(CW$sha1\fR
 252 object:
 253 .Sp
 254 .Vb 4
 255 \&    $sha1\->add("a"); $sha1\->add("b"); $sha1\->add("c");
 256 \&    $sha1\->add("a")\->add("b")\->add("c");
 257 \&    $sha1\->add("a", "b", "c");
 258 \&    $sha1\->add("abc");
 259 .Ve
 260 .ie n .IP "$sha1\->addfile($io_handle)" 4
 261 .el .IP "\f(CW$sha1\fR\->addfile($io_handle)" 4
 262 .IX Item "$sha1->addfile($io_handle)"
 263 The \f(CW$io_handle\fR will be read until \s-1EOF\s0 and its content appended to the
 264 message we calculate the digest for.  The return value is the \f(CW$sha1\fR
 265 object itself.
 266 .Sp
 267 The \fIaddfile()\fR method will \fIcroak()\fR if it fails reading data for some
 268 reason.  If it croaks it is unpredictable what the state of the \f(CW$sha1\fR
 269 object will be in. The \fIaddfile()\fR method might have been able to read
 270 the file partially before it failed.  It is probably wise to discard
 271 or reset the \f(CW$sha1\fR object if this occurs.
 272 .Sp
 273 In most cases you want to make sure that the \f(CW$io_handle\fR is in
 274 \&\f(CW\*(C`binmode\*(C'\fR before you pass it as argument to the \fIaddfile()\fR method.
 275 .ie n .IP "$sha1\->add_bits($data, $nbits)" 4
 276 .el .IP "\f(CW$sha1\fR\->add_bits($data, \f(CW$nbits\fR)" 4
 277 .IX Item "$sha1->add_bits($data, $nbits)"
 278 .PD 0
 279 .ie n .IP "$sha1\->add_bits($bitstring)" 4
 280 .el .IP "\f(CW$sha1\fR\->add_bits($bitstring)" 4
 281 .IX Item "$sha1->add_bits($bitstring)"
 282 .PD
 283 This implementation of \s-1SHA\-1\s0 only supports byte oriented input so you
 284 might only add bits as multiples of 8.  If you need bit level support
 285 please consider using the \f(CW\*(C`Digest::SHA\*(C'\fR module instead.  The
 286 \&\fIadd_bits()\fR method is provided here for compatibility with other digest
 287 implementations.  See Digest for description of the arguments that
 288 \&\fIadd_bits()\fR take.
 289 .ie n .IP "$sha1\->digest" 4
 290 .el .IP "\f(CW$sha1\fR\->digest" 4
 291 .IX Item "$sha1->digest"
 292 Return the binary digest for the message.  The returned string will be
 293 20 bytes long.
 294 .Sp
 295 Note that the \f(CW\*(C`digest\*(C'\fR operation is effectively a destructive,
 296 read-once operation. Once it has been performed, the \f(CW\*(C`Digest::SHA1\*(C'\fR
 297 object is automatically \f(CW\*(C`reset\*(C'\fR and can be used to calculate another
 298 digest value.  Call \f(CW$sha1\fR\->clone\->digest if you want to calculate the
 299 digest without reseting the digest state.
 300 .ie n .IP "$sha1\->hexdigest" 4
 301 .el .IP "\f(CW$sha1\fR\->hexdigest" 4
 302 .IX Item "$sha1->hexdigest"
 303 Same as \f(CW$sha1\fR\->digest, but will return the digest in hexadecimal
 304 form. The length of the returned string will be 40 and it will only
 305 contain characters from this set: '0'..'9' and 'a'..'f'.
 306 .ie n .IP "$sha1\->b64digest" 4
 307 .el .IP "\f(CW$sha1\fR\->b64digest" 4
 308 .IX Item "$sha1->b64digest"
 309 Same as \f(CW$sha1\fR\->digest, but will return the digest as a base64 encoded
 310 string.  The length of the returned string will be 27 and it will only
 311 contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+'
 312 and '/'.
 313 .Sp
 314 The base64 encoded string returned is not padded to be a multiple of 4
 315 bytes long.  If you want interoperability with other base64 encoded
 316 \&\s-1SHA\-1\s0 digests you might want to append the string \*(L"=\*(R" to the result.
 317 .SH "SEE ALSO"
 318 .IX Header "SEE ALSO"
 319 Digest, Digest::HMAC_SHA1, Digest::SHA, Digest::MD5
 320 .PP
 321 http://www.itl.nist.gov/fipspubs/fip180\-1.htm
 322 .PP
 323 http://en.wikipedia.org/wiki/SHA_hash_functions
 324 .SH "COPYRIGHT"
 325 .IX Header "COPYRIGHT"
 326 This library is free software; you can redistribute it and/or
 327 modify it under the same terms as Perl itself.
 328 .PP
 329 .Vb 2
 330 \& Copyright 1999\-2004 Gisle Aas.
 331 \& Copyright 1997 Uwe Hollerbach.
 332 .Ve
 333 .SH "AUTHORS"
 334 .IX Header "AUTHORS"
 335 Peter C. Gutmann,
 336 Uwe Hollerbach <uh@alumni.caltech.edu>,
 337 Gisle Aas <gisle@aas.no>