"Fossies" - the Fresh Open Source Software Archive

Member "install-tl-20200916/tlpkg/tlperl/lib/Digest.pm" (18 Apr 2017, 10701 Bytes) of package /windows/misc/install-tl.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

    1 package Digest;
    2 
    3 use strict;
    4 use vars qw($VERSION %MMAP $AUTOLOAD);
    5 
    6 $VERSION = "1.17_01";
    7 
    8 %MMAP = (
    9   "SHA-1"      => [["Digest::SHA", 1], "Digest::SHA1", ["Digest::SHA2", 1]],
   10   "SHA-224"    => [["Digest::SHA", 224]],
   11   "SHA-256"    => [["Digest::SHA", 256], ["Digest::SHA2", 256]],
   12   "SHA-384"    => [["Digest::SHA", 384], ["Digest::SHA2", 384]],
   13   "SHA-512"    => [["Digest::SHA", 512], ["Digest::SHA2", 512]],
   14   "HMAC-MD5"   => "Digest::HMAC_MD5",
   15   "HMAC-SHA-1" => "Digest::HMAC_SHA1",
   16   "CRC-16"     => [["Digest::CRC", type => "crc16"]],
   17   "CRC-32"     => [["Digest::CRC", type => "crc32"]],
   18   "CRC-CCITT"  => [["Digest::CRC", type => "crcccitt"]],
   19   "RIPEMD-160" => "Crypt::RIPEMD160",
   20 );
   21 
   22 sub new
   23 {
   24     shift;  # class ignored
   25     my $algorithm = shift;
   26     my $impl = $MMAP{$algorithm} || do {
   27         $algorithm =~ s/\W+//g;
   28         "Digest::$algorithm";
   29     };
   30     $impl = [$impl] unless ref($impl);
   31     local $@;  # don't clobber it for our caller
   32     my $err;
   33     for  (@$impl) {
   34         my $class = $_;
   35         my @args;
   36         ($class, @args) = @$class if ref($class);
   37         no strict 'refs';
   38         unless (exists ${"$class\::"}{"VERSION"}) {
   39             my $pm_file = $class . ".pm";
   40             $pm_file =~ s{::}{/}g;
   41             eval {
   42                 local @INC = @INC;
   43                 pop @INC if $INC[-1] eq '.';
   44                 require $pm_file
   45         };
   46             if ($@) {
   47                 $err ||= $@;
   48                 next;
   49             }
   50         }
   51         return $class->new(@args, @_);
   52     }
   53     die $err;
   54 }
   55 
   56 sub AUTOLOAD
   57 {
   58     my $class = shift;
   59     my $algorithm = substr($AUTOLOAD, rindex($AUTOLOAD, '::')+2);
   60     $class->new($algorithm, @_);
   61 }
   62 
   63 1;
   64 
   65 __END__
   66 
   67 =head1 NAME
   68 
   69 Digest - Modules that calculate message digests
   70 
   71 =head1 SYNOPSIS
   72 
   73   $md5  = Digest->new("MD5");
   74   $sha1 = Digest->new("SHA-1");
   75   $sha256 = Digest->new("SHA-256");
   76   $sha384 = Digest->new("SHA-384");
   77   $sha512 = Digest->new("SHA-512");
   78 
   79   $hmac = Digest->HMAC_MD5($key);
   80 
   81 =head1 DESCRIPTION
   82 
   83 The C<Digest::> modules calculate digests, also called "fingerprints"
   84 or "hashes", of some data, called a message.  The digest is (usually)
   85 some small/fixed size string.  The actual size of the digest depend of
   86 the algorithm used.  The message is simply a sequence of arbitrary
   87 bytes or bits.
   88 
   89 An important property of the digest algorithms is that the digest is
   90 I<likely> to change if the message change in some way.  Another
   91 property is that digest functions are one-way functions, that is it
   92 should be I<hard> to find a message that correspond to some given
   93 digest.  Algorithms differ in how "likely" and how "hard", as well as
   94 how efficient they are to compute.
   95 
   96 Note that the properties of the algorithms change over time, as the
   97 algorithms are analyzed and machines grow faster.  If your application
   98 for instance depends on it being "impossible" to generate the same
   99 digest for a different message it is wise to make it easy to plug in
  100 stronger algorithms as the one used grow weaker.  Using the interface
  101 documented here should make it easy to change algorithms later.
  102 
  103 All C<Digest::> modules provide the same programming interface.  A
  104 functional interface for simple use, as well as an object oriented
  105 interface that can handle messages of arbitrary length and which can
  106 read files directly.
  107 
  108 The digest can be delivered in three formats:
  109 
  110 =over 8
  111 
  112 =item I<binary>
  113 
  114 This is the most compact form, but it is not well suited for printing
  115 or embedding in places that can't handle arbitrary data.
  116 
  117 =item I<hex>
  118 
  119 A twice as long string of lowercase hexadecimal digits.
  120 
  121 =item I<base64>
  122 
  123 A string of portable printable characters.  This is the base64 encoded
  124 representation of the digest with any trailing padding removed.  The
  125 string will be about 30% longer than the binary version.
  126 L<MIME::Base64> tells you more about this encoding.
  127 
  128 =back
  129 
  130 
  131 The functional interface is simply importable functions with the same
  132 name as the algorithm.  The functions take the message as argument and
  133 return the digest.  Example:
  134 
  135   use Digest::MD5 qw(md5);
  136   $digest = md5($message);
  137 
  138 There are also versions of the functions with "_hex" or "_base64"
  139 appended to the name, which returns the digest in the indicated form.
  140 
  141 =head1 OO INTERFACE
  142 
  143 The following methods are available for all C<Digest::> modules:
  144 
  145 =over 4
  146 
  147 =item $ctx = Digest->XXX($arg,...)
  148 
  149 =item $ctx = Digest->new(XXX => $arg,...)
  150 
  151 =item $ctx = Digest::XXX->new($arg,...)
  152 
  153 The constructor returns some object that encapsulate the state of the
  154 message-digest algorithm.  You can add data to the object and finally
  155 ask for the digest.  The "XXX" should of course be replaced by the proper
  156 name of the digest algorithm you want to use.
  157 
  158 The two first forms are simply syntactic sugar which automatically
  159 load the right module on first use.  The second form allow you to use
  160 algorithm names which contains letters which are not legal perl
  161 identifiers, e.g. "SHA-1".  If no implementation for the given algorithm
  162 can be found, then an exception is raised.
  163 
  164 If new() is called as an instance method (i.e. $ctx->new) it will just
  165 reset the state the object to the state of a newly created object.  No
  166 new object is created in this case, and the return value is the
  167 reference to the object (i.e. $ctx).
  168 
  169 =item $other_ctx = $ctx->clone
  170 
  171 The clone method creates a copy of the digest state object and returns
  172 a reference to the copy.
  173 
  174 =item $ctx->reset
  175 
  176 This is just an alias for $ctx->new.
  177 
  178 =item $ctx->add( $data )
  179 
  180 =item $ctx->add( $chunk1, $chunk2, ... )
  181 
  182 The string value of the $data provided as argument is appended to the
  183 message we calculate the digest for.  The return value is the $ctx
  184 object itself.
  185 
  186 If more arguments are provided then they are all appended to the
  187 message, thus all these lines will have the same effect on the state
  188 of the $ctx object:
  189 
  190   $ctx->add("a"); $ctx->add("b"); $ctx->add("c");
  191   $ctx->add("a")->add("b")->add("c");
  192   $ctx->add("a", "b", "c");
  193   $ctx->add("abc");
  194 
  195 Most algorithms are only defined for strings of bytes and this method
  196 might therefore croak if the provided arguments contain chars with
  197 ordinal number above 255.
  198 
  199 =item $ctx->addfile( $io_handle )
  200 
  201 The $io_handle is read until EOF and the content is appended to the
  202 message we calculate the digest for.  The return value is the $ctx
  203 object itself.
  204 
  205 The addfile() method will croak() if it fails reading data for some
  206 reason.  If it croaks it is unpredictable what the state of the $ctx
  207 object will be in. The addfile() method might have been able to read
  208 the file partially before it failed.  It is probably wise to discard
  209 or reset the $ctx object if this occurs.
  210 
  211 In most cases you want to make sure that the $io_handle is in
  212 "binmode" before you pass it as argument to the addfile() method.
  213 
  214 =item $ctx->add_bits( $data, $nbits )
  215 
  216 =item $ctx->add_bits( $bitstring )
  217 
  218 The add_bits() method is an alternative to add() that allow partial
  219 bytes to be appended to the message.  Most users should just ignore
  220 this method as partial bytes is very unlikely to be of any practical
  221 use.
  222 
  223 The two argument form of add_bits() will add the first $nbits bits
  224 from $data.  For the last potentially partial byte only the high order
  225 C<< $nbits % 8 >> bits are used.  If $nbits is greater than C<<
  226 length($data) * 8 >>, then this method would do the same as C<<
  227 $ctx->add($data) >>.
  228 
  229 The one argument form of add_bits() takes a $bitstring of "1" and "0"
  230 chars as argument.  It's a shorthand for C<< $ctx->add_bits(pack("B*",
  231 $bitstring), length($bitstring)) >>.
  232 
  233 The return value is the $ctx object itself.
  234 
  235 This example shows two calls that should have the same effect:
  236 
  237    $ctx->add_bits("111100001010");
  238    $ctx->add_bits("\xF0\xA0", 12);
  239 
  240 Most digest algorithms are byte based and for these it is not possible
  241 to add bits that are not a multiple of 8, and the add_bits() method
  242 will croak if you try.
  243 
  244 =item $ctx->digest
  245 
  246 Return the binary digest for the message.
  247 
  248 Note that the C<digest> operation is effectively a destructive,
  249 read-once operation. Once it has been performed, the $ctx object is
  250 automatically C<reset> and can be used to calculate another digest
  251 value.  Call $ctx->clone->digest if you want to calculate the digest
  252 without resetting the digest state.
  253 
  254 =item $ctx->hexdigest
  255 
  256 Same as $ctx->digest, but will return the digest in hexadecimal form.
  257 
  258 =item $ctx->b64digest
  259 
  260 Same as $ctx->digest, but will return the digest as a base64 encoded
  261 string.
  262 
  263 =back
  264 
  265 =head1 Digest speed
  266 
  267 This table should give some indication on the relative speed of
  268 different algorithms.  It is sorted by throughput based on a benchmark
  269 done with of some implementations of this API:
  270 
  271  Algorithm      Size    Implementation                  MB/s
  272 
  273  MD4            128     Digest::MD4 v1.3               165.0
  274  MD5            128     Digest::MD5 v2.33               98.8
  275  SHA-256        256     Digest::SHA2 v1.1.0             66.7
  276  SHA-1          160     Digest::SHA v4.3.1              58.9
  277  SHA-1          160     Digest::SHA1 v2.10              48.8
  278  SHA-256        256     Digest::SHA v4.3.1              41.3
  279  Haval-256      256     Digest::Haval256 v1.0.4         39.8
  280  SHA-384        384     Digest::SHA2 v1.1.0             19.6
  281  SHA-512        512     Digest::SHA2 v1.1.0             19.3
  282  SHA-384        384     Digest::SHA v4.3.1              19.2
  283  SHA-512        512     Digest::SHA v4.3.1              19.2
  284  Whirlpool      512     Digest::Whirlpool v1.0.2        13.0
  285  MD2            128     Digest::MD2 v2.03                9.5
  286 
  287  Adler-32        32     Digest::Adler32 v0.03            1.3
  288  CRC-16          16     Digest::CRC v0.05                1.1
  289  CRC-32          32     Digest::CRC v0.05                1.1
  290  MD5            128     Digest::Perl::MD5 v1.5           1.0
  291  CRC-CCITT       16     Digest::CRC v0.05                0.8
  292 
  293 These numbers was achieved Apr 2004 with ActivePerl-5.8.3 running
  294 under Linux on a P4 2.8 GHz CPU.  The last 5 entries differ by being
  295 pure perl implementations of the algorithms, which explains why they
  296 are so slow.
  297 
  298 =head1 SEE ALSO
  299 
  300 L<Digest::Adler32>, L<Digest::CRC>, L<Digest::Haval256>,
  301 L<Digest::HMAC>, L<Digest::MD2>, L<Digest::MD4>, L<Digest::MD5>,
  302 L<Digest::SHA>, L<Digest::SHA1>, L<Digest::SHA2>, L<Digest::Whirlpool>
  303 
  304 New digest implementations should consider subclassing from L<Digest::base>.
  305 
  306 L<MIME::Base64>
  307 
  308 http://en.wikipedia.org/wiki/Cryptographic_hash_function
  309 
  310 =head1 AUTHOR
  311 
  312 Gisle Aas <gisle@aas.no>
  313 
  314 The C<Digest::> interface is based on the interface originally
  315 developed by Neil Winton for his C<MD5> module.
  316 
  317 This library is free software; you can redistribute it and/or
  318 modify it under the same terms as Perl itself.
  319 
  320     Copyright 1998-2006 Gisle Aas.
  321     Copyright 1995,1996 Neil Winton.
  322 
  323 =cut