diff options
author | Siep Kroonenberg <siepo@cybercomm.nl> | 2011-02-17 17:57:31 +0000 |
---|---|---|
committer | Siep Kroonenberg <siepo@cybercomm.nl> | 2011-02-17 17:57:31 +0000 |
commit | 320d8694fec25ed148613684543b5a0504a046ae (patch) | |
tree | 0ddcf933d3acd3c98a387fa2bf73d0554ca6e50d /Master/tlpkg/tlperl/lib/Digest | |
parent | 779e71f16ca01a6244b632b95bdb461fec163b34 (diff) |
New tlperl part XIV
git-svn-id: svn://tug.org/texlive/trunk@21436 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Digest')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Digest/MD5.pm | 376 | ||||
-rw-r--r-- | Master/tlpkg/tlperl/lib/Digest/SHA.pm | 669 | ||||
-rw-r--r-- | Master/tlpkg/tlperl/lib/Digest/SHA1.pm | 246 | ||||
-rw-r--r-- | Master/tlpkg/tlperl/lib/Digest/base.pm | 100 | ||||
-rw-r--r-- | Master/tlpkg/tlperl/lib/Digest/file.pm | 85 |
5 files changed, 1476 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Digest/MD5.pm b/Master/tlpkg/tlperl/lib/Digest/MD5.pm new file mode 100644 index 00000000000..4e2adbe3460 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Digest/MD5.pm @@ -0,0 +1,376 @@ +package Digest::MD5; + +use strict; +use vars qw($VERSION @ISA @EXPORT_OK); + +$VERSION = '2.39'; + +require Exporter; +*import = \&Exporter::import; +@EXPORT_OK = qw(md5 md5_hex md5_base64); + +eval { + require Digest::base; + push(@ISA, 'Digest::base'); +}; +if ($@) { + my $err = $@; + *add_bits = sub { die $err }; +} + + +eval { + require XSLoader; + XSLoader::load('Digest::MD5', $VERSION); +}; +if ($@) { + my $olderr = $@; + eval { + # Try to load the pure perl version + require Digest::Perl::MD5; + + Digest::Perl::MD5->import(qw(md5 md5_hex md5_base64)); + push(@ISA, "Digest::Perl::MD5"); # make OO interface work + }; + if ($@) { + # restore the original error + die $olderr; + } +} +else { + *reset = \&new; +} + +1; +__END__ + +=head1 NAME + +Digest::MD5 - Perl interface to the MD5 Algorithm + +=head1 SYNOPSIS + + # 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; + +=head1 DESCRIPTION + +The C<Digest::MD5> module allows you to use the RSA Data Security +Inc. MD5 Message Digest algorithm from within Perl programs. The +algorithm takes as input a message of arbitrary length and produces as +output a 128-bit "fingerprint" or "message digest" of the input. + +Note that the MD5 algorithm is not as strong as it used to be. It has +since 2005 been easy to generate different messages that produce the +same MD5 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. + +The C<Digest::MD5> 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. + +=head1 FUNCTIONS + +The following functions are provided by the C<Digest::MD5> module. +None of these functions are exported by default. + +=over 4 + +=item md5($data,...) + +This function will concatenate all arguments, calculate the MD5 digest +of this "message", and return it in binary form. The returned string +will be 16 bytes long. + +The result of md5("a", "b", "c") will be exactly the same as the +result of md5("abc"). + +=item md5_hex($data,...) + +Same as md5(), 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'. + +=item md5_base64($data,...) + +Same as md5(), 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 +'/'. + +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 "==" to the result. + +=back + +=head1 METHODS + +The object oriented interface to C<Digest::MD5> is described in this +section. After a C<Digest::MD5> 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. + +The following methods are provided: + +=over 4 + +=item $md5 = Digest::MD5->new + +The constructor returns a new C<Digest::MD5> object which encapsulate +the state of the MD5 message-digest algorithm. + +If called as an instance method (i.e. $md5->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. + +=item $md5->reset + +This is just an alias for $md5->new. + +=item $md5->clone + +This a copy of the $md5 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: + + my $md5 = Digest::MD5->new; + while (<>) { + $md5->add($_); + print "Line $.: ", $md5->clone->hexdigest, "\n"; + } + +=item $md5->add($data,...) + +The $data provided as argument are appended to the message we +calculate the digest for. The return value is the $md5 object itself. + +All these lines will have the same effect on the state of the $md5 +object: + + $md5->add("a"); $md5->add("b"); $md5->add("c"); + $md5->add("a")->add("b")->add("c"); + $md5->add("a", "b", "c"); + $md5->add("abc"); + +=item $md5->addfile($io_handle) + +The $io_handle will be read until EOF and its content appended to the +message we calculate the digest for. The return value is the $md5 +object itself. + +The addfile() method will croak() if it fails reading data for some +reason. If it croaks it is unpredictable what the state of the $md5 +object will be in. The addfile() method might have been able to read +the file partially before it failed. It is probably wise to discard +or reset the $md5 object if this occurs. + +In most cases you want to make sure that the $io_handle is in +C<binmode> before you pass it as argument to the addfile() method. + +=item $md5->add_bits($data, $nbits) + +=item $md5->add_bits($bitstring) + +Since the MD5 algorithm is byte oriented you might only add bits as +multiples of 8, so you probably want to just use add() instead. The +add_bits() method is provided for compatibility with other digest +implementations. See L<Digest> for description of the arguments +that add_bits() take. + +=item $md5->digest + +Return the binary digest for the message. The returned string will be +16 bytes long. + +Note that the C<digest> operation is effectively a destructive, +read-once operation. Once it has been performed, the C<Digest::MD5> +object is automatically C<reset> and can be used to calculate another +digest value. Call $md5->clone->digest if you want to calculate the +digest without resetting the digest state. + +=item $md5->hexdigest + +Same as $md5->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'. + +=item $md5->b64digest + +Same as $md5->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 '/'. + + +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 "==" to the result. + +=back + + +=head1 EXAMPLES + +The simplest way to use this library is to import the md5_hex() +function (or one of its cousins): + + use Digest::MD5 qw(md5_hex); + print "Digest is ", md5_hex("foobarbaz"), "\n"; + +The above example would print out the message: + + Digest is 6df23dc03f9b54cc38a0fc1483df6e21 + +The same checksum can also be calculated in OO style: + + use Digest::MD5; + + $md5 = Digest::MD5->new; + $md5->add('foo', 'bar'); + $md5->add('baz'); + $digest = $md5->hexdigest; + + print "Digest is $digest\n"; + +With OO 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. + +This is useful when calculating checksum for files: + + use Digest::MD5; + + my $file = shift || "/etc/passwd"; + open(FILE, $file) or die "Can't open '$file': $!"; + binmode(FILE); + + $md5 = Digest::MD5->new; + while (<FILE>) { + $md5->add($_); + } + close(FILE); + print $md5->b64digest, " $file\n"; + +Or we can use the addfile method for more efficient reading of +the file: + + use Digest::MD5; + + my $file = shift || "/etc/passwd"; + open(FILE, $file) or die "Can't open '$file': $!"; + binmode(FILE); + + print Digest::MD5->new->addfile(*FILE)->hexdigest, " $file\n"; + +Perl 5.8 support Unicode characters in strings. Since the MD5 +algorithm is only defined for strings of bytes, it can not be used on +strings that contains chars with ordinal number above 255. The MD5 +functions and methods will croak if you try to feed them such input +data: + + use Digest::MD5 qw(md5_hex); + + my $str = "abc\x{300}"; + print md5_hex($str), "\n"; # croaks + # Wide character in subroutine entry + +What you can do is calculate the MD5 checksum of the UTF-8 +representation of such strings. This is achieved by filtering the +string through encode_utf8() function: + + use Digest::MD5 qw(md5_hex); + use Encode qw(encode_utf8); + + my $str = "abc\x{300}"; + print md5_hex(encode_utf8($str)), "\n"; + # 8c2d46911f3f5a326455f0ed7a8ed3b3 + +=head1 SEE ALSO + +L<Digest>, +L<Digest::MD2>, +L<Digest::SHA>, +L<Digest::HMAC> + +L<md5sum(1)> + +RFC 1321 + +http://en.wikipedia.org/wiki/MD5 + +The paper "How to Break MD5 and Other Hash Functions" by Xiaoyun Wang +and Hongbo Yu. + +=head1 COPYRIGHT + +This library is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + + Copyright 1998-2003 Gisle Aas. + Copyright 1995-1996 Neil Winton. + Copyright 1991-1992 RSA Data Security, Inc. + +The MD5 algorithm is defined in RFC 1321. This implementation is +derived from the reference C code in RFC 1321 which is covered by +the following copyright statement: + +=over 4 + +=item + +Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All +rights reserved. + +License to copy and use this software is granted provided that it +is identified as the "RSA Data Security, Inc. MD5 Message-Digest +Algorithm" in all material mentioning or referencing this software +or this function. + +License is also granted to make and use derivative works provided +that such works are identified as "derived from the RSA Data +Security, Inc. MD5 Message-Digest Algorithm" in all material +mentioning or referencing the derived work. + +RSA 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 "as is" +without express or implied warranty of any kind. + +These notices must be retained in any copies of any part of this +documentation and/or software. + +=back + +This copyright does not prohibit distribution of any version of Perl +containing this extension under the terms of the GNU or Artistic +licenses. + +=head1 AUTHORS + +The original C<MD5> interface was written by Neil Winton +(C<N.Winton@axion.bt.co.uk>). + +The C<Digest::MD5> module is written by Gisle Aas <gisle@ActiveState.com>. + +=cut diff --git a/Master/tlpkg/tlperl/lib/Digest/SHA.pm b/Master/tlpkg/tlperl/lib/Digest/SHA.pm new file mode 100644 index 00000000000..d57c16fce59 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Digest/SHA.pm @@ -0,0 +1,669 @@ +package Digest::SHA; + +require 5.003000; + +use strict; +use integer; +use vars qw($VERSION @ISA @EXPORT @EXPORT_OK); + +$VERSION = '5.47'; + +require Exporter; +require DynaLoader; +@ISA = qw(Exporter DynaLoader); +@EXPORT_OK = qw( + hmac_sha1 hmac_sha1_base64 hmac_sha1_hex + hmac_sha224 hmac_sha224_base64 hmac_sha224_hex + hmac_sha256 hmac_sha256_base64 hmac_sha256_hex + hmac_sha384 hmac_sha384_base64 hmac_sha384_hex + hmac_sha512 hmac_sha512_base64 hmac_sha512_hex + sha1 sha1_base64 sha1_hex + sha224 sha224_base64 sha224_hex + sha256 sha256_base64 sha256_hex + sha384 sha384_base64 sha384_hex + sha512 sha512_base64 sha512_hex); + +# If possible, inherit from Digest::base (which depends on MIME::Base64) + +*addfile = \&Addfile; + +eval { + require MIME::Base64; + require Digest::base; + push(@ISA, 'Digest::base'); +}; +if ($@) { + *hexdigest = \&Hexdigest; + *b64digest = \&B64digest; +} + +# The following routines aren't time-critical, so they can be left in Perl + +sub new { + my($class, $alg) = @_; + $alg =~ s/\D+//g if defined $alg; + if (ref($class)) { # instance method + unless (defined($alg) && ($alg != $class->algorithm)) { + sharewind($$class); + return($class); + } + shaclose($$class) if $$class; + $$class = shaopen($alg) || return; + return($class); + } + $alg = 1 unless defined $alg; + my $state = shaopen($alg) || return; + my $self = \$state; + bless($self, $class); + return($self); +} + +sub DESTROY { + my $self = shift; + shaclose($$self) if $$self; +} + +sub clone { + my $self = shift; + my $state = shadup($$self) || return; + my $copy = \$state; + bless($copy, ref($self)); + return($copy); +} + +*reset = \&new; + +sub add_bits { + my($self, $data, $nbits) = @_; + unless (defined $nbits) { + $nbits = length($data); + $data = pack("B*", $data); + } + shawrite($data, $nbits, $$self); + return($self); +} + +sub _bail { + my $msg = shift; + + require Carp; + Carp::croak("$msg: $!"); +} + +sub _addfile { # this is "addfile" from Digest::base 1.00 + my ($self, $handle) = @_; + + my $n; + my $buf = ""; + + while (($n = read($handle, $buf, 4096))) { + $self->add($buf); + } + _bail("Read failed") unless defined $n; + + $self; +} + +sub Addfile { + my ($self, $file, $mode) = @_; + + return(_addfile($self, $file)) unless ref(\$file) eq 'SCALAR'; + + $mode = defined($mode) ? $mode : ""; + my ($binary, $portable) = map { $_ eq $mode } ("b", "p"); + my $text = -T $file; + + local *FH; + # protect any leading or trailing whitespace in $file; + # otherwise, 2-arg "open" will ignore them + $file =~ s#^(\s)#./$1#; + open(FH, "< $file\0") or _bail("Open failed"); + binmode(FH) if $binary || $portable; + + unless ($portable && $text) { + $self->_addfile(*FH); + close(FH); + return($self); + } + + my ($n1, $n2); + my ($buf1, $buf2) = ("", ""); + + while (($n1 = read(FH, $buf1, 4096))) { + while (substr($buf1, -1) eq "\015") { + $n2 = read(FH, $buf2, 4096); + _bail("Read failed") unless defined $n2; + last unless $n2; + $buf1 .= $buf2; + } + $buf1 =~ s/\015?\015\012/\012/g; # DOS/Windows + $buf1 =~ s/\015/\012/g; # early MacOS + $self->add($buf1); + } + _bail("Read failed") unless defined $n1; + close(FH); + + $self; +} + +sub dump { + my $self = shift; + my $file = shift || ""; + + shadump($file, $$self) || return; + return($self); +} + +sub load { + my $class = shift; + my $file = shift || ""; + if (ref($class)) { # instance method + shaclose($$class) if $$class; + $$class = shaload($file) || return; + return($class); + } + my $state = shaload($file) || return; + my $self = \$state; + bless($self, $class); + return($self); +} + +Digest::SHA->bootstrap($VERSION); + +1; +__END__ + +=head1 NAME + +Digest::SHA - Perl extension for SHA-1/224/256/384/512 + +=head1 SYNOPSIS + +In programs: + + # 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; # if needed, make copy of + $sha->dump($file); # current digest state, + $sha->load($file); # or save it on disk + + $digest = $sha->digest; # compute digest + $digest = $sha->hexdigest; + $digest = $sha->b64digest; + +From the command line: + + $ shasum files + + $ shasum --help + +=head1 SYNOPSIS (HMAC-SHA) + + # 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); + +=head1 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, and SHA-512 message digests. +The module can handle all types of input, including partial-byte +data. + +=head1 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) L<Digest::SHA::PurePerl> module. + +The programming interface is easy to use: it's the same one found +in CPAN's L<Digest> module. So, if your applications currently +use L<Digest::MD5> and you'd prefer the stronger security of SHA, +it's a simple matter to convert them. + +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: + + 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!\n" : "oops!\n"; + +To calculate the digest of an n-bit message where I<n> is not a +multiple of 8, use the I<add_bits()> 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: + + use Digest::SHA; + $bits = "110" x 148 . "11"; + $sha = Digest::SHA->new(1)->add_bits($bits); + print $sha->hexdigest, "\n"; + +Note that for larger bit-strings, it's more efficient to use the +two-argument version I<add_bits($data, $nbits)>, where I<$data> is +in the customary packed binary format used for Perl strings. + +The module also lets you save intermediate SHA states to disk, or +display them on standard output. The I<dump()> method generates +portable, human-readable text describing the current state of +computation. You can subsequently retrieve the file with I<load()> +to resume where the calculation left off. + +To see what a state description looks like, just run the following: + + use Digest::SHA; + Digest::SHA->new->add("Shaw" x 1962)->dump; + +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 I<sha()>, I<sha_hex()>, and +I<sha_base64()> functions. + + # 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), "\n"; + +=head1 NIST STATEMENT ON SHA-1 + +I<NIST was recently informed that researchers had discovered a way +to "break" the current Federal Information Processing Standard SHA-1 +algorithm, which has been in effect since 1994. The researchers +have not yet published their complete results, so NIST has not +confirmed these findings. However, the researchers are a reputable +research team with expertise in this area.> + +I<Due to advances in computing power, NIST already planned to phase +out SHA-1 in favor of the larger and stronger hash functions (SHA-224, +SHA-256, SHA-384 and SHA-512) by 2010. New developments should use +the larger and stronger hash functions.> + +ref. L<http://www.csrc.nist.gov/pki/HashWorkshop/NIST%20Statement/Burr_Mar2005.html> + +=head1 PADDING OF BASE64 DIGESTS + +By convention, CPAN Digest modules do B<not> pad their Base64 output. +Problems can occur when feeding such digests to other software that +expects properly padded Base64 encodings. + +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: + + while (length($b64_digest) % 4) { + $b64_digest .= '='; + } + +To illustrate, I<sha256_base64("abc")> is computed to be + + ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0 + +which has a length of 43. So, the properly padded version is + + ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0= + +=head1 EXPORT + +None by default. + +=head1 EXPORTABLE FUNCTIONS + +Provided your C compiler supports a 64-bit type (e.g. the I<long +long> of C99, or I<__int64> 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. + +I<Functional style> + +=over 4 + +=item B<sha1($data, ...)> + +=item B<sha224($data, ...)> + +=item B<sha256($data, ...)> + +=item B<sha384($data, ...)> + +=item B<sha512($data, ...)> + +Logically joins the arguments into a single string, and returns +its SHA-1/224/256/384/512 digest encoded as a binary string. + +=item B<sha1_hex($data, ...)> + +=item B<sha224_hex($data, ...)> + +=item B<sha256_hex($data, ...)> + +=item B<sha384_hex($data, ...)> + +=item B<sha512_hex($data, ...)> + +Logically joins the arguments into a single string, and returns +its SHA-1/224/256/384/512 digest encoded as a hexadecimal string. + +=item B<sha1_base64($data, ...)> + +=item B<sha224_base64($data, ...)> + +=item B<sha256_base64($data, ...)> + +=item B<sha384_base64($data, ...)> + +=item B<sha512_base64($data, ...)> + +Logically joins the arguments into a single string, and returns +its SHA-1/224/256/384/512 digest encoded as a Base64 string. + +It's important to note that the resulting string does B<not> 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 L</"PADDING OF BASE64 DIGESTS"> for details. + +=back + +I<OOP style> + +=over 4 + +=item B<new($alg)> + +Returns a new Digest::SHA object. Allowed values for I<$alg> are +1, 224, 256, 384, or 512. 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. + +Invoking I<new> as an instance method will not create a new object; +instead, it will simply reset the object to the initial state +associated with I<$alg>. If the argument is missing, the object +will continue using the same algorithm that was selected at creation. + +=item B<reset($alg)> + +This method has exactly the same effect as I<new($alg)>. In fact, +I<reset> is just an alias for I<new>. + +=item B<hashsize> + +Returns the number of digest bits for this object. The values are +160, 224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384, +and SHA-512, respectively. + +=item B<algorithm> + +Returns the digest algorithm for this object. The values are 1, +224, 256, 384, and 512 for SHA-1, SHA-224, SHA-256, SHA-384, and +SHA-512, respectively. + +=item B<clone> + +Returns a duplicate copy of the object. + +=item B<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: + + $sha->add("a"); $sha->add("b"); $sha->add("c"); + $sha->add("a")->add("b")->add("c"); + $sha->add("a", "b", "c"); + $sha->add("abc"); + +The return value is the updated object itself. + +=item B<add_bits($data, $nbits)> + +=item B<add_bits($bits)> + +Updates the current digest state by appending bits to it. The +return value is the updated object itself. + +The first form causes the most-significant I<$nbits> of I<$data> +to be appended to the stream. The I<$data> argument is in the +customary binary format used for Perl strings. + +The second form takes an ASCII string of "0" and "1" characters as +its argument. It's equivalent to + + $sha->add_bits(pack("B*", $bits), length($bits)); + +So, the following two statements do the same thing: + + $sha->add_bits("111100001010"); + $sha->add_bits("\xF0\xA0", 12); + +=item B<addfile(*FILE)> + +Reads from I<FILE> until EOF, and appends that data to the current +state. The return value is the updated object itself. + +=item B<addfile($filename [, $mode])> + +Reads the contents of I<$filename>, and appends that data to the current +state. The return value is the updated object itself. + +By default, I<$filename> is simply opened and read; no special modes +or I/O disciplines are used. To change this, set the optional I<$mode> +argument to one of the following values: + + "b" read file in binary mode + + "p" use portable mode + +The "p" mode is handy since it ensures that the digest value of +I<$filename> will be the same when computed on different operating +systems. It accomplishes this by internally translating all newlines in +text files to UNIX format before calculating the digest. Binary files +are read in raw mode with no translation whatsoever. + +For a fuller discussion of newline formats, refer to CPAN module +L<File::LocalizeNewlines>. Its "universal line separator" regex forms +the basis of I<addfile>'s portable mode processing. + +=item B<dump($filename)> + +Provides persistent storage of intermediate SHA states by writing +a portable, human-readable representation of the current state to +I<$filename>. If the argument is missing, or equal to the empty +string, the state information will be written to STDOUT. + +=item B<load($filename)> + +Returns a Digest::SHA object representing the intermediate SHA +state that was previously dumped to I<$filename>. 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 I<$filename>. +If the argument is missing, or equal to the empty string, the state +information will be read from STDIN. + +=item B<digest> + +Returns the digest encoded as a binary string. + +Note that the I<digest> 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 +I<$sha-E<gt>clone-E<gt>digest> if it's necessary to preserve the +original digest state. + +=item B<hexdigest> + +Returns the digest encoded as a hexadecimal string. + +Like I<digest>, this method is a read-once operation. Call +I<$sha-E<gt>clone-E<gt>hexdigest> if it's necessary to preserve +the original digest state. + +This method is inherited if L<Digest::base> is installed on your +system. Otherwise, a functionally equivalent substitute is used. + +=item B<b64digest> + +Returns the digest encoded as a Base64 string. + +Like I<digest>, this method is a read-once operation. Call +I<$sha-E<gt>clone-E<gt>b64digest> if it's necessary to preserve +the original digest state. + +This method is inherited if L<Digest::base> is installed on your +system. Otherwise, a functionally equivalent substitute is used. + +It's important to note that the resulting string does B<not> 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 L</"PADDING OF BASE64 DIGESTS"> for details. + +=back + +I<HMAC-SHA-1/224/256/384/512> + +=over 4 + +=item B<hmac_sha1($data, $key)> + +=item B<hmac_sha224($data, $key)> + +=item B<hmac_sha256($data, $key)> + +=item B<hmac_sha384($data, $key)> + +=item B<hmac_sha512($data, $key)> + +Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>, +with the result encoded as a binary string. Multiple I<$data> +arguments are allowed, provided that I<$key> is the last argument +in the list. + +=item B<hmac_sha1_hex($data, $key)> + +=item B<hmac_sha224_hex($data, $key)> + +=item B<hmac_sha256_hex($data, $key)> + +=item B<hmac_sha384_hex($data, $key)> + +=item B<hmac_sha512_hex($data, $key)> + +Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>, +with the result encoded as a hexadecimal string. Multiple I<$data> +arguments are allowed, provided that I<$key> is the last argument +in the list. + +=item B<hmac_sha1_base64($data, $key)> + +=item B<hmac_sha224_base64($data, $key)> + +=item B<hmac_sha256_base64($data, $key)> + +=item B<hmac_sha384_base64($data, $key)> + +=item B<hmac_sha512_base64($data, $key)> + +Returns the HMAC-SHA-1/224/256/384/512 digest of I<$data>/I<$key>, +with the result encoded as a Base64 string. Multiple I<$data> +arguments are allowed, provided that I<$key> is the last argument +in the list. + +It's important to note that the resulting string does B<not> 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 L</"PADDING OF BASE64 DIGESTS"> for details. + +=back + +=head1 SEE ALSO + +L<Digest>, L<Digest::SHA::PurePerl> + +The Secure Hash Standard (FIPS PUB 180-2) can be found at: + +L<http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf> + +The Keyed-Hash Message Authentication Code (HMAC): + +L<http://csrc.nist.gov/publications/fips/fips198/fips-198a.pdf> + +=head1 AUTHOR + + Mark Shelor <mshelor@cpan.org> + +=head1 ACKNOWLEDGMENTS + +The author is particularly grateful to + + Gisle Aas + Chris Carey + Alexandr Ciornii + Jim Doble + Julius Duque + Jeffrey Friedl + Robert Gilmour + Brian Gladman + Adam Kennedy + Andy Lester + Alex Muntada + Steve Peters + Chris Skiscim + Martin Thurn + Gunnar Wolf + Adam Woodbury + +for their valuable comments and suggestions. + +=head1 COPYRIGHT AND LICENSE + +Copyright (C) 2003-2008 Mark Shelor + +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. + +L<perlartistic> + +=cut diff --git a/Master/tlpkg/tlperl/lib/Digest/SHA1.pm b/Master/tlpkg/tlperl/lib/Digest/SHA1.pm new file mode 100644 index 00000000000..bd2647a1de3 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Digest/SHA1.pm @@ -0,0 +1,246 @@ +package Digest::SHA1; + +use strict; +use vars qw($VERSION @ISA @EXPORT_OK); + +$VERSION = '2.13'; + +require Exporter; +*import = \&Exporter::import; +@EXPORT_OK = qw(sha1 sha1_hex sha1_base64 sha1_transform); + +require DynaLoader; +@ISA=qw(DynaLoader); + +eval { + require Digest::base; + push(@ISA, 'Digest::base'); +}; +if ($@) { + my $err = $@; + *add_bits = sub { die $err }; +} + +Digest::SHA1->bootstrap($VERSION); + +1; +__END__ + +=head1 NAME + +Digest::SHA1 - Perl interface to the SHA-1 algorithm + +=head1 SYNOPSIS + + # 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; + +=head1 DESCRIPTION + +The C<Digest::SHA1> module allows you to use the NIST SHA-1 message +digest algorithm from within Perl programs. The algorithm takes as +input a message of arbitrary length and produces as output a 160-bit +"fingerprint" or "message digest" of the input. + +In 2005, security flaws were identified in SHA-1, namely that a possible +mathematical weakness might exist, indicating that a stronger hash function +would be desirable. The L<Digest::SHA> module implements the stronger +algorithms in the SHA family. + +The C<Digest::SHA1> 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. + +=head1 FUNCTIONS + +The following functions can be exported from the C<Digest::SHA1> +module. No functions are exported by default. + +=over 4 + +=item sha1($data,...) + +This function will concatenate all arguments, calculate the SHA-1 +digest of this "message", and return it in binary form. The returned +string will be 20 bytes long. + +The result of sha1("a", "b", "c") will be exactly the same as the +result of sha1("abc"). + +=item sha1_hex($data,...) + +Same as sha1(), 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'. + +=item sha1_base64($data,...) + +Same as sha1(), 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 +'/'. + +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 "=" to the result. + +=item sha1_transform($data) + +Implements the basic SHA1 transform on a 64 byte block. The $data +argument and the returned $digest are in binary form. This algorithm +is used in NIST FIPS 186-2 + +=back + +=head1 METHODS + +The object oriented interface to C<Digest::SHA1> is described in this +section. After a C<Digest::SHA1> 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. + +The following methods are provided: + +=over 4 + +=item $sha1 = Digest::SHA1->new + +The constructor returns a new C<Digest::SHA1> object which encapsulate +the state of the SHA-1 message-digest algorithm. + +If called as an instance method (i.e. $sha1->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. + +=item $sha1->reset + +This is just an alias for $sha1->new. + +=item $sha1->clone + +This a copy of the $sha1 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: + + my $sha1 = Digest::SHA1->new; + while (<>) { + $sha1->add($_); + print "Line $.: ", $sha1->clone->hexdigest, "\n"; + } + +=item $sha1->add($data,...) + +The $data provided as argument are appended to the message we +calculate the digest for. The return value is the $sha1 object itself. + +All these lines will have the same effect on the state of the $sha1 +object: + + $sha1->add("a"); $sha1->add("b"); $sha1->add("c"); + $sha1->add("a")->add("b")->add("c"); + $sha1->add("a", "b", "c"); + $sha1->add("abc"); + +=item $sha1->addfile($io_handle) + +The $io_handle will be read until EOF and its content appended to the +message we calculate the digest for. The return value is the $sha1 +object itself. + +The addfile() method will croak() if it fails reading data for some +reason. If it croaks it is unpredictable what the state of the $sha1 +object will be in. The addfile() method might have been able to read +the file partially before it failed. It is probably wise to discard +or reset the $sha1 object if this occurs. + +In most cases you want to make sure that the $io_handle is in +C<binmode> before you pass it as argument to the addfile() method. + +=item $sha1->add_bits($data, $nbits) + +=item $sha1->add_bits($bitstring) + +This implementation of SHA-1 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 C<Digest::SHA> module instead. The +add_bits() method is provided here for compatibility with other digest +implementations. See L<Digest> for description of the arguments that +add_bits() take. + +=item $sha1->digest + +Return the binary digest for the message. The returned string will be +20 bytes long. + +Note that the C<digest> operation is effectively a destructive, +read-once operation. Once it has been performed, the C<Digest::SHA1> +object is automatically C<reset> and can be used to calculate another +digest value. Call $sha1->clone->digest if you want to calculate the +digest without reseting the digest state. + +=item $sha1->hexdigest + +Same as $sha1->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'. + +=item $sha1->b64digest + +Same as $sha1->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 '/'. + + +The base64 encoded string returned is not padded to be a multiple of 4 +bytes long. If you want interoperability with other base64 encoded +SHA-1 digests you might want to append the string "=" to the result. + +=back + +=head1 SEE ALSO + +L<Digest>, L<Digest::HMAC_SHA1>, L<Digest::SHA>, L<Digest::MD5> + +http://www.itl.nist.gov/fipspubs/fip180-1.htm + +http://en.wikipedia.org/wiki/SHA_hash_functions + +=head1 COPYRIGHT + +This library is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. + + Copyright 1999-2004 Gisle Aas. + Copyright 1997 Uwe Hollerbach. + +=head1 AUTHORS + +Peter C. Gutmann, +Uwe Hollerbach <uh@alumni.caltech.edu>, +Gisle Aas <gisle@aas.no> + +=cut diff --git a/Master/tlpkg/tlperl/lib/Digest/base.pm b/Master/tlpkg/tlperl/lib/Digest/base.pm new file mode 100644 index 00000000000..b2844ba3400 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Digest/base.pm @@ -0,0 +1,100 @@ +package Digest::base; + +use strict; +use vars qw($VERSION); +$VERSION = "1.16"; + +# subclass is supposed to implement at least these +sub new; +sub clone; +sub add; +sub digest; + +sub reset { + my $self = shift; + $self->new(@_); # ugly +} + +sub addfile { + my ($self, $handle) = @_; + + my $n; + my $buf = ""; + + while (($n = read($handle, $buf, 4*1024))) { + $self->add($buf); + } + unless (defined $n) { + require Carp; + Carp::croak("Read failed: $!"); + } + + $self; +} + +sub add_bits { + my $self = shift; + my $bits; + my $nbits; + if (@_ == 1) { + my $arg = shift; + $bits = pack("B*", $arg); + $nbits = length($arg); + } + else { + ($bits, $nbits) = @_; + } + if (($nbits % 8) != 0) { + require Carp; + Carp::croak("Number of bits must be multiple of 8 for this algorithm"); + } + return $self->add(substr($bits, 0, $nbits/8)); +} + +sub hexdigest { + my $self = shift; + return unpack("H*", $self->digest(@_)); +} + +sub b64digest { + my $self = shift; + require MIME::Base64; + my $b64 = MIME::Base64::encode($self->digest(@_), ""); + $b64 =~ s/=+$//; + return $b64; +} + +1; + +__END__ + +=head1 NAME + +Digest::base - Digest base class + +=head1 SYNOPSIS + + package Digest::Foo; + use base 'Digest::base'; + +=head1 DESCRIPTION + +The C<Digest::base> class provide implementations of the methods +C<addfile> and C<add_bits> in terms of C<add>, and of the methods +C<hexdigest> and C<b64digest> in terms of C<digest>. + +Digest implementations might want to inherit from this class to get +this implementations of the alternative I<add> and I<digest> methods. +A minimal subclass needs to implement the following methods by itself: + + new + clone + add + digest + +The arguments and expected behaviour of these methods are described in +L<Digest>. + +=head1 SEE ALSO + +L<Digest> diff --git a/Master/tlpkg/tlperl/lib/Digest/file.pm b/Master/tlpkg/tlperl/lib/Digest/file.pm new file mode 100644 index 00000000000..3b86e63503a --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Digest/file.pm @@ -0,0 +1,85 @@ +package Digest::file; + +use strict; + +use Exporter (); +use Carp qw(croak); +use Digest (); + +use vars qw($VERSION @ISA @EXPORT_OK); + +$VERSION = "1.16"; +@ISA = qw(Exporter); +@EXPORT_OK = qw(digest_file_ctx digest_file digest_file_hex digest_file_base64); + +sub digest_file_ctx { + my $file = shift; + croak("No digest algorithm specified") unless @_; + local *F; + open(F, "<", $file) || croak("Can't open '$file': $!"); + binmode(F); + my $ctx = Digest->new(@_); + $ctx->addfile(*F); + close(F); + return $ctx; +} + +sub digest_file { + digest_file_ctx(@_)->digest; +} + +sub digest_file_hex { + digest_file_ctx(@_)->hexdigest; +} + +sub digest_file_base64 { + digest_file_ctx(@_)->b64digest; +} + +1; + +__END__ + +=head1 NAME + +Digest::file - Calculate digests of files + +=head1 SYNOPSIS + + # Poor mans "md5sum" command + use Digest::file qw(digest_file_hex); + for (@ARGV) { + print digest_file_hex($_, "MD5"), " $_\n"; + } + +=head1 DESCRIPTION + +This module provide 3 convenience functions to calculate the digest +of files. The following functions are provided: + +=over + +=item digest_file( $file, $algorithm, [$arg,...] ) + +This function will calculate and return the binary digest of the bytes +of the given file. The function will croak if it fails to open or +read the file. + +The $algorithm is a string like "MD2", "MD5", "SHA-1", "SHA-512". +Additional arguments are passed to the constructor for the +implementation of the given algorithm. + +=item digest_file_hex( $file, $algorithm, [$arg,...] ) + +Same as digest_file(), but return the digest in hex form. + +=item digest_file_base64( $file, $algorithm, [$arg,...] ) + +Same as digest_file(), but return the digest as a base64 encoded +string. + +=back + +=head1 SEE ALSO + +L<Digest> |