--- /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 "MD5 3"
+.TH MD5 3 "2009-06-09" "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::MD5 \- Perl interface to the MD5 Algorithm
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 2
+\& # Functional style
+\& use Digest::MD5 qw(md5 md5_hex md5_base64);
+\&
+\& $digest = md5($data);
+\& $digest = md5_hex($data);
+\& $digest = md5_base64($data);
+\&
+\& # OO style
+\& use Digest::MD5;
+\&
+\& $ctx = Digest::MD5\->new;
+\&
+\& $ctx\->add($data);
+\& $ctx\->addfile(*FILE);
+\&
+\& $digest = $ctx\->digest;
+\& $digest = $ctx\->hexdigest;
+\& $digest = $ctx\->b64digest;
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \f(CW\*(C`Digest::MD5\*(C'\fR module allows you to use the \s-1RSA\s0 Data Security
+Inc. \s-1MD5\s0 Message Digest algorithm from within Perl programs. The
+algorithm takes as input a message of arbitrary length and produces as
+output a 128\-bit \*(L"fingerprint\*(R" or \*(L"message digest\*(R" of the input.
+.PP
+Note that the \s-1MD5\s0 algorithm is not as strong as it used to be. It has
+since 2005 been easy to generate different messages that produce the
+same \s-1MD5\s0 digest. It still seems hard to generate messages that
+produce a given digest, but it is probably wise to move to stronger
+algorithms for applications that depend on the digest to uniquely identify
+a message.
+.PP
+The \f(CW\*(C`Digest::MD5\*(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 are provided by the \f(CW\*(C`Digest::MD5\*(C'\fR module.
+None of these functions are exported by default.
+.IP "md5($data,...)" 4
+.IX Item "md5($data,...)"
+This function will concatenate all arguments, calculate the \s-1MD5\s0 digest
+of this \*(L"message\*(R", and return it in binary form. The returned string
+will be 16 bytes long.
+.Sp
+The result of md5(\*(L"a\*(R", \*(L"b\*(R", \*(L"c\*(R") will be exactly the same as the
+result of md5(\*(L"abc\*(R").
+.IP "md5_hex($data,...)" 4
+.IX Item "md5_hex($data,...)"
+Same as \fImd5()\fR, but will return the digest in hexadecimal form. The
+length of the returned string will be 32 and it will only contain
+characters from this set: '0'..'9' and 'a'..'f'.
+.IP "md5_base64($data,...)" 4
+.IX Item "md5_base64($data,...)"
+Same as \fImd5()\fR, but will return the digest as a base64 encoded string.
+The length of the returned string will be 22 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 md5 digests you might want to append the redundant
+string \*(L"==\*(R" to the result.
+.SH "METHODS"
+.IX Header "METHODS"
+The object oriented interface to \f(CW\*(C`Digest::MD5\*(C'\fR is described in this
+section. After a \f(CW\*(C`Digest::MD5\*(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 "$md5 = Digest::MD5\->new" 4
+.el .IP "\f(CW$md5\fR = Digest::MD5\->new" 4
+.IX Item "$md5 = Digest::MD5->new"
+The constructor returns a new \f(CW\*(C`Digest::MD5\*(C'\fR object which encapsulate
+the state of the \s-1MD5\s0 message-digest algorithm.
+.Sp
+If called as an instance method (i.e. \f(CW$md5\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 "$md5\->reset" 4
+.el .IP "\f(CW$md5\fR\->reset" 4
+.IX Item "$md5->reset"
+This is just an alias for \f(CW$md5\fR\->new.
+.ie n .IP "$md5\->clone" 4
+.el .IP "\f(CW$md5\fR\->clone" 4
+.IX Item "$md5->clone"
+This a copy of the \f(CW$md5\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 $md5 = Digest::MD5\->new;
+\& while (<>) {
+\& $md5\->add($_);
+\& print "Line $.: ", $md5\->clone\->hexdigest, "\en";
+\& }
+.Ve
+.ie n .IP "$md5\->add($data,...)" 4
+.el .IP "\f(CW$md5\fR\->add($data,...)" 4
+.IX Item "$md5->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$md5\fR object itself.
+.Sp
+All these lines will have the same effect on the state of the \f(CW$md5\fR
+object:
+.Sp
+.Vb 4
+\& $md5\->add("a"); $md5\->add("b"); $md5\->add("c");
+\& $md5\->add("a")\->add("b")\->add("c");
+\& $md5\->add("a", "b", "c");
+\& $md5\->add("abc");
+.Ve
+.ie n .IP "$md5\->addfile($io_handle)" 4
+.el .IP "\f(CW$md5\fR\->addfile($io_handle)" 4
+.IX Item "$md5->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$md5\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$md5\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$md5\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 "$md5\->add_bits($data, $nbits)" 4
+.el .IP "\f(CW$md5\fR\->add_bits($data, \f(CW$nbits\fR)" 4
+.IX Item "$md5->add_bits($data, $nbits)"
+.PD 0
+.ie n .IP "$md5\->add_bits($bitstring)" 4
+.el .IP "\f(CW$md5\fR\->add_bits($bitstring)" 4
+.IX Item "$md5->add_bits($bitstring)"
+.PD
+Since the \s-1MD5\s0 algorithm is byte oriented you might only add bits as
+multiples of 8, so you probably want to just use \fIadd()\fR instead. The
+\&\fIadd_bits()\fR method is provided for compatibility with other digest
+implementations. See Digest for description of the arguments
+that \fIadd_bits()\fR take.
+.ie n .IP "$md5\->digest" 4
+.el .IP "\f(CW$md5\fR\->digest" 4
+.IX Item "$md5->digest"
+Return the binary digest for the message. The returned string will be
+16 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::MD5\*(C'\fR
+object is automatically \f(CW\*(C`reset\*(C'\fR and can be used to calculate another
+digest value. Call \f(CW$md5\fR\->clone\->digest if you want to calculate the
+digest without resetting the digest state.
+.ie n .IP "$md5\->hexdigest" 4
+.el .IP "\f(CW$md5\fR\->hexdigest" 4
+.IX Item "$md5->hexdigest"
+Same as \f(CW$md5\fR\->digest, but will return the digest in hexadecimal
+form. The length of the returned string will be 32 and it will only
+contain characters from this set: '0'..'9' and 'a'..'f'.
+.ie n .IP "$md5\->b64digest" 4
+.el .IP "\f(CW$md5\fR\->b64digest" 4
+.IX Item "$md5->b64digest"
+Same as \f(CW$md5\fR\->digest, but will return the digest as a base64 encoded
+string. The length of the returned string will be 22 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
+md5 digests you might want to append the string \*(L"==\*(R" to the result.
+.SH "EXAMPLES"
+.IX Header "EXAMPLES"
+The simplest way to use this library is to import the \fImd5_hex()\fR
+function (or one of its cousins):
+.PP
+.Vb 2
+\& use Digest::MD5 qw(md5_hex);
+\& print "Digest is ", md5_hex("foobarbaz"), "\en";
+.Ve
+.PP
+The above example would print out the message:
+.PP
+.Vb 1
+\& Digest is 6df23dc03f9b54cc38a0fc1483df6e21
+.Ve
+.PP
+The same checksum can also be calculated in \s-1OO\s0 style:
+.PP
+.Vb 1
+\& use Digest::MD5;
+\&
+\& $md5 = Digest::MD5\->new;
+\& $md5\->add(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq);
+\& $md5\->add(\*(Aqbaz\*(Aq);
+\& $digest = $md5\->hexdigest;
+\&
+\& print "Digest is $digest\en";
+.Ve
+.PP
+With \s-1OO\s0 style you can break the message arbitrary. This means that we
+are no longer limited to have space for the whole message in memory, i.e.
+we can handle messages of any size.
+.PP
+This is useful when calculating checksum for files:
+.PP
+.Vb 1
+\& use Digest::MD5;
+\&
+\& my $file = shift || "/etc/passwd";
+\& open(FILE, $file) or die "Can\*(Aqt open \*(Aq$file\*(Aq: $!";
+\& binmode(FILE);
+\&
+\& $md5 = Digest::MD5\->new;
+\& while (<FILE>) {
+\& $md5\->add($_);
+\& }
+\& close(FILE);
+\& print $md5\->b64digest, " $file\en";
+.Ve
+.PP
+Or we can use the addfile method for more efficient reading of
+the file:
+.PP
+.Vb 1
+\& use Digest::MD5;
+\&
+\& my $file = shift || "/etc/passwd";
+\& open(FILE, $file) or die "Can\*(Aqt open \*(Aq$file\*(Aq: $!";
+\& binmode(FILE);
+\&
+\& print Digest::MD5\->new\->addfile(*FILE)\->hexdigest, " $file\en";
+.Ve
+.PP
+Perl 5.8 support Unicode characters in strings. Since the \s-1MD5\s0
+algorithm is only defined for strings of bytes, it can not be used on
+strings that contains chars with ordinal number above 255. The \s-1MD5\s0
+functions and methods will croak if you try to feed them such input
+data:
+.PP
+.Vb 1
+\& use Digest::MD5 qw(md5_hex);
+\&
+\& my $str = "abc\ex{300}";
+\& print md5_hex($str), "\en"; # croaks
+\& # Wide character in subroutine entry
+.Ve
+.PP
+What you can do is calculate the \s-1MD5\s0 checksum of the \s-1UTF\-8\s0
+representation of such strings. This is achieved by filtering the
+string through \fIencode_utf8()\fR function:
+.PP
+.Vb 2
+\& use Digest::MD5 qw(md5_hex);
+\& use Encode qw(encode_utf8);
+\&
+\& my $str = "abc\ex{300}";
+\& print md5_hex(encode_utf8($str)), "\en";
+\& # 8c2d46911f3f5a326455f0ed7a8ed3b3
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Digest,
+Digest::MD2,
+Digest::SHA,
+Digest::HMAC
+.PP
+\&\fImd5sum\fR\|(1)
+.PP
+\&\s-1RFC\s0 1321
+.PP
+http://en.wikipedia.org/wiki/MD5
+.PP
+The paper \*(L"How to Break \s-1MD5\s0 and Other Hash Functions\*(R" by Xiaoyun Wang
+and Hongbo Yu.
+.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 3
+\& Copyright 1998\-2003 Gisle Aas.
+\& Copyright 1995\-1996 Neil Winton.
+\& Copyright 1991\-1992 RSA Data Security, Inc.
+.Ve
+.PP
+The \s-1MD5\s0 algorithm is defined in \s-1RFC\s0 1321. This implementation is
+derived from the reference C code in \s-1RFC\s0 1321 which is covered by
+the following copyright statement:
+.IP "\(bu" 4
+Copyright (C) 1991\-2, \s-1RSA\s0 Data Security, Inc. Created 1991. All
+rights reserved.
+.Sp
+License to copy and use this software is granted provided that it
+is identified as the \*(L"\s-1RSA\s0 Data Security, Inc. \s-1MD5\s0 Message-Digest
+Algorithm\*(R" in all material mentioning or referencing this software
+or this function.
+.Sp
+License is also granted to make and use derivative works provided
+that such works are identified as \*(L"derived from the \s-1RSA\s0 Data
+Security, Inc. \s-1MD5\s0 Message-Digest Algorithm\*(R" in all material
+mentioning or referencing the derived work.
+.Sp
+\&\s-1RSA\s0 Data Security, Inc. makes no representations concerning either
+the merchantability of this software or the suitability of this
+software for any particular purpose. It is provided \*(L"as is\*(R"
+without express or implied warranty of any kind.
+.Sp
+These notices must be retained in any copies of any part of this
+documentation and/or software.
+.PP
+This copyright does not prohibit distribution of any version of Perl
+containing this extension under the terms of the \s-1GNU\s0 or Artistic
+licenses.
+.SH "AUTHORS"
+.IX Header "AUTHORS"
+The original \f(CW\*(C`MD5\*(C'\fR interface was written by Neil Winton
+(\f(CW\*(C`N.Winton@axion.bt.co.uk\*(C'\fR).
+.PP
+The \f(CW\*(C`Digest::MD5\*(C'\fR module is written by Gisle Aas <gisle@ActiveState.com>.
projects / catagits/Gitalist.git / blobdiff