--- /dev/null
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
+.\"
+.\" 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
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'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 turned on, 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.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "SHA1 3"
+.TH SHA1 3 "2009-05-23" "perl v5.8.7" "User Contributed Perl Documentation"
+.\" 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::SHA1 \- Perl interface to the SHA\-1 algorithm
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 2
+\& # Functional style
+\& use Digest::SHA1 qw(sha1 sha1_hex sha1_base64);
+\&
+\& $digest = sha1($data);
+\& $digest = sha1_hex($data);
+\& $digest = sha1_base64($data);
+\& $digest = sha1_transform($data);
+\&
+\&
+\& # OO style
+\& use Digest::SHA1;
+\&
+\& $sha1 = Digest::SHA1\->new;
+\&
+\& $sha1\->add($data);
+\& $sha1\->addfile(*FILE);
+\&
+\& $sha1_copy = $sha1\->clone;
+\&
+\& $digest = $sha1\->digest;
+\& $digest = $sha1\->hexdigest;
+\& $digest = $sha1\->b64digest;
+\& $digest = $sha1\->transform;
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \f(CW\*(C`Digest::SHA1\*(C'\fR module allows you to use the \s-1NIST\s0 \s-1SHA\-1\s0 message
+digest algorithm from within Perl programs. The algorithm takes as
+input a message of arbitrary length and produces as output a 160\-bit
+\&\*(L"fingerprint\*(R" or \*(L"message digest\*(R" of the input.
+.PP
+In 2005, security flaws were identified in \s-1SHA\-1\s0, namely that a possible
+mathematical weakness might exist, indicating that a stronger hash function
+would be desirable. The Digest::SHA module implements the stronger
+algorithms in the \s-1SHA\s0 family.
+.PP
+The \f(CW\*(C`Digest::SHA1\*(C'\fR module provide a procedural interface for simple
+use, as well as an object oriented interface that can handle messages
+of arbitrary length and which can read files directly.
+.SH "FUNCTIONS"
+.IX Header "FUNCTIONS"
+The following functions can be exported from the \f(CW\*(C`Digest::SHA1\*(C'\fR
+module. No functions are exported by default.
+.IP "sha1($data,...)" 4
+.IX Item "sha1($data,...)"
+This function will concatenate all arguments, calculate the \s-1SHA\-1\s0
+digest of this \*(L"message\*(R", and return it in binary form. The returned
+string will be 20 bytes long.
+.Sp
+The result of sha1(\*(L"a\*(R", \*(L"b\*(R", \*(L"c\*(R") will be exactly the same as the
+result of sha1(\*(L"abc\*(R").
+.IP "sha1_hex($data,...)" 4
+.IX Item "sha1_hex($data,...)"
+Same as \fIsha1()\fR, but will return the digest in hexadecimal form. The
+length of the returned string will be 40 and it will only contain
+characters from this set: '0'..'9' and 'a'..'f'.
+.IP "sha1_base64($data,...)" 4
+.IX Item "sha1_base64($data,...)"
+Same as \fIsha1()\fR, but will return the digest as a base64 encoded string.
+The length of the returned string will be 27 and it will only contain
+characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+' and
+\&'/'.
+.Sp
+Note that the base64 encoded string returned is not padded to be a
+multiple of 4 bytes long. If you want interoperability with other
+base64 encoded sha1 digests you might want to append the redundant
+string \*(L"=\*(R" to the result.
+.IP "sha1_transform($data)" 4
+.IX Item "sha1_transform($data)"
+Implements the basic \s-1SHA1\s0 transform on a 64 byte block. The \f(CW$data\fR
+argument and the returned \f(CW$digest\fR are in binary form. This algorithm
+is used in \s-1NIST\s0 \s-1FIPS\s0 186\-2
+.SH "METHODS"
+.IX Header "METHODS"
+The object oriented interface to \f(CW\*(C`Digest::SHA1\*(C'\fR is described in this
+section. After a \f(CW\*(C`Digest::SHA1\*(C'\fR object has been created, you will add
+data to it and finally ask for the digest in a suitable format. A
+single object can be used to calculate multiple digests.
+.PP
+The following methods are provided:
+.ie n .IP "$sha1 = Digest::SHA1\->new" 4
+.el .IP "\f(CW$sha1\fR = Digest::SHA1\->new" 4
+.IX Item "$sha1 = Digest::SHA1->new"
+The constructor returns a new \f(CW\*(C`Digest::SHA1\*(C'\fR object which encapsulate
+the state of the \s-1SHA\-1\s0 message-digest algorithm.
+.Sp
+If called as an instance method (i.e. \f(CW$sha1\fR\->new) it will just reset the
+state the object to the state of a newly created object. No new
+object is created in this case.
+.ie n .IP "$sha1\->reset" 4
+.el .IP "\f(CW$sha1\fR\->reset" 4
+.IX Item "$sha1->reset"
+This is just an alias for \f(CW$sha1\fR\->new.
+.ie n .IP "$sha1\->clone" 4
+.el .IP "\f(CW$sha1\fR\->clone" 4
+.IX Item "$sha1->clone"
+This a copy of the \f(CW$sha1\fR object. It is useful when you do not want to
+destroy the digests state, but need an intermediate value of the
+digest, e.g. when calculating digests iteratively on a continuous data
+stream. Example:
+.Sp
+.Vb 5
+\& my $sha1 = Digest::SHA1\->new;
+\& while (<>) {
+\& $sha1\->add($_);
+\& print "Line $.: ", $sha1\->clone\->hexdigest, "\en";
+\& }
+.Ve
+.ie n .IP "$sha1\->add($data,...)" 4
+.el .IP "\f(CW$sha1\fR\->add($data,...)" 4
+.IX Item "$sha1->add($data,...)"
+The \f(CW$data\fR provided as argument are appended to the message we
+calculate the digest for. The return value is the \f(CW$sha1\fR object itself.
+.Sp
+All these lines will have the same effect on the state of the \f(CW$sha1\fR
+object:
+.Sp
+.Vb 4
+\& $sha1\->add("a"); $sha1\->add("b"); $sha1\->add("c");
+\& $sha1\->add("a")\->add("b")\->add("c");
+\& $sha1\->add("a", "b", "c");
+\& $sha1\->add("abc");
+.Ve
+.ie n .IP "$sha1\->addfile($io_handle)" 4
+.el .IP "\f(CW$sha1\fR\->addfile($io_handle)" 4
+.IX Item "$sha1->addfile($io_handle)"
+The \f(CW$io_handle\fR will be read until \s-1EOF\s0 and its content appended to the
+message we calculate the digest for. The return value is the \f(CW$sha1\fR
+object itself.
+.Sp
+The \fIaddfile()\fR method will \fIcroak()\fR if it fails reading data for some
+reason. If it croaks it is unpredictable what the state of the \f(CW$sha1\fR
+object will be in. The \fIaddfile()\fR method might have been able to read
+the file partially before it failed. It is probably wise to discard
+or reset the \f(CW$sha1\fR object if this occurs.
+.Sp
+In most cases you want to make sure that the \f(CW$io_handle\fR is in
+\&\f(CW\*(C`binmode\*(C'\fR before you pass it as argument to the \fIaddfile()\fR method.
+.ie n .IP "$sha1\->add_bits($data, $nbits)" 4
+.el .IP "\f(CW$sha1\fR\->add_bits($data, \f(CW$nbits\fR)" 4
+.IX Item "$sha1->add_bits($data, $nbits)"
+.PD 0
+.ie n .IP "$sha1\->add_bits($bitstring)" 4
+.el .IP "\f(CW$sha1\fR\->add_bits($bitstring)" 4
+.IX Item "$sha1->add_bits($bitstring)"
+.PD
+This implementation of \s-1SHA\-1\s0 only supports byte oriented input so you
+might only add bits as multiples of 8. If you need bit level support
+please consider using the \f(CW\*(C`Digest::SHA\*(C'\fR module instead. The
+\&\fIadd_bits()\fR method is provided here for compatibility with other digest
+implementations. See Digest for description of the arguments that
+\&\fIadd_bits()\fR take.
+.ie n .IP "$sha1\->digest" 4
+.el .IP "\f(CW$sha1\fR\->digest" 4
+.IX Item "$sha1->digest"
+Return the binary digest for the message. The returned string will be
+20 bytes long.
+.Sp
+Note that the \f(CW\*(C`digest\*(C'\fR operation is effectively a destructive,
+read-once operation. Once it has been performed, the \f(CW\*(C`Digest::SHA1\*(C'\fR
+object is automatically \f(CW\*(C`reset\*(C'\fR and can be used to calculate another
+digest value. Call \f(CW$sha1\fR\->clone\->digest if you want to calculate the
+digest without reseting the digest state.
+.ie n .IP "$sha1\->hexdigest" 4
+.el .IP "\f(CW$sha1\fR\->hexdigest" 4
+.IX Item "$sha1->hexdigest"
+Same as \f(CW$sha1\fR\->digest, but will return the digest in hexadecimal
+form. The length of the returned string will be 40 and it will only
+contain characters from this set: '0'..'9' and 'a'..'f'.
+.ie n .IP "$sha1\->b64digest" 4
+.el .IP "\f(CW$sha1\fR\->b64digest" 4
+.IX Item "$sha1->b64digest"
+Same as \f(CW$sha1\fR\->digest, but will return the digest as a base64 encoded
+string. The length of the returned string will be 27 and it will only
+contain characters from this set: 'A'..'Z', 'a'..'z', '0'..'9', '+'
+and '/'.
+.Sp
+The base64 encoded string returned is not padded to be a multiple of 4
+bytes long. If you want interoperability with other base64 encoded
+\&\s-1SHA\-1\s0 digests you might want to append the string \*(L"=\*(R" to the result.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Digest, Digest::HMAC_SHA1, Digest::SHA, Digest::MD5
+.PP
+http://www.itl.nist.gov/fipspubs/fip180\-1.htm
+.PP
+http://en.wikipedia.org/wiki/SHA_hash_functions
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+This library is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+.PP
+.Vb 2
+\& Copyright 1999\-2004 Gisle Aas.
+\& Copyright 1997 Uwe Hollerbach.
+.Ve
+.SH "AUTHORS"
+.IX Header "AUTHORS"
+Peter C. Gutmann,
+Uwe Hollerbach <uh@alumni.caltech.edu>,
+Gisle Aas <gisle@aas.no>
projects / catagits/Gitalist.git / blobdiff