Assimilate Digest 1.05

p4raw-id: //depot/perl@21973

1 files changed, 50 insertions, 12 deletions

diff --git a/lib/Digest.pm b/lib/Digest.pm
index c0e9cc105f..9353db13dc 100644
--- a/lib/Digest.pm
+++ b/lib/Digest.pm
@@ -3,7 +3,7 @@ package Digest;
 use strict;
 use vars qw($VERSION %MMAP $AUTOLOAD);
 
-$VERSION = "1.03";
+$VERSION = "1.05";
 
 %MMAP = (
   "SHA-1"      => ["Digest::SHA1", ["Digest::SHA", 1], ["Digest::SHA2", 1]],
@@ -54,15 +54,15 @@ __END__
 
 =head1 NAME
 
-Digest:: - Modules that calculate message digests
+Digest - Modules that calculate message digests
 
 =head1 SYNOPSIS
 
-  $md2 = Digest->MD2;
-  $md5 = Digest->MD5;
-
-  $sha1 = Digest->SHA1;
+  $md5  = Digest->new("MD5");
   $sha1 = Digest->new("SHA-1");
+  $sha256 = Digest->new("SHA-256");
+  $sha384 = Digest->new("SHA-384");
+  $sha512 = Digest->new("SHA-512");
 
   $hmac = Digest->HMAC_MD5($key);
 
@@ -97,7 +97,7 @@ or embedding in places that can't handle arbitrary data.
 
 =item I<hex>
 
-A twice as long string of (lowercase) hexadecimal digits.
+A twice as long string of lowercase hexadecimal digits.
 
 =item I<base64>
 
@@ -155,20 +155,20 @@ a reference to the copy.
 
 This is just an alias for $ctx->new.
 
-=item $ctx->add($data,...)
+=item $ctx->add( $data, ... )
 
 The $data provided as argument are appended to the message we
 calculate the digest for.  The return value is the $ctx object itself.
 
-=item $ctx->addfile($io_handle)
+=item $ctx->addfile( $io_handle )
 
 The $io_handle is read until EOF and the content is appended to the
 message we calculate the digest for.  The return value is the $ctx
 object itself.
 
-=item $ctx->add_bits($data, $nbits)
+=item $ctx->add_bits( $data, $nbits )
 
-=item $ctx->add_bits($bitstring)
+=item $ctx->add_bits( $bitstring )
 
 The bits provided are appended to the message we calculate the digest
 for.  The return value is the $ctx object itself.
@@ -213,9 +213,41 @@ string.
 
 =back
 
+=head1 Digest speed
+
+This table should give some indication on the relative speed of
+different algorithms.  It is sorted by throughput based on a benchmark
+done with of some implementations of this API:
+
+ Algorithm	Size	Implementation			MB/s
+
+ MD4		128	Digest::MD4 v1.1		24.9
+ MD5		128	Digest::MD5 v2.30		18.7
+ Haval-256	256	Digest::Haval256 v1.0.4		17.0
+ SHA-1		160	Digest::SHA1 v2.06		15.3
+ SHA-1		160	Digest::SHA v4.0.0		10.1
+ SHA-256	256	Digest::SHA2 v1.0.0	 	 7.6
+ SHA-256	256	Digest::SHA v4.0.0	 	 6.5
+ SHA-384	384	Digest::SHA2 v1.0.0	 	 2.7
+ SHA-384	384	Digest::SHA v4.0.0	 	 2.7
+ SHA-512	512	Digest::SHA2 v1.0.0		 2.7
+ SHA-512	512	Digest::SHA v4.0.0		 2.7
+ Whirlpool	512	Digest::Whirlpool v1.0.2	 1.4
+ MD2		128	Digest::MD2 v2.03		 1.1
+
+ Adler-32	 32	Digest::Adler32 v0.03	 	 0.2
+ MD5		128	Digest::Perl::MD5 v1.5		 0.1
+
+These numbers was achieved Nov 2003 with ActivePerl-5.8.1 running
+under Linux on a P-II 350 MHz CPU.  The last 2 entries differ by being
+pure perl implementations of the algorithms, which explains why they
+are so slow.
+
 =head1 SEE ALSO
 
-L<Digest::MD5>, L<Digest::SHA1>, L<Digest::HMAC>, L<Digest::MD2>
+L<Digest::Adler32>, L<Digest::Haval256>, L<Digest::HMAC>, L<Digest::MD2>, L<Digest::MD4>, L<Digest::MD5>, L<Digest::SHA>, L<Digest::SHA1>, L<Digest::SHA2>, L<Digest::Whirlpool>
+
+New digest implementations should consider subclassing from L<Digest::base>.
 
 L<MIME::Base64>
 
@@ -226,4 +258,10 @@ Gisle Aas <gisle@aas.no>
 The C<Digest::> interface is based on the interface originally
 developed by Neil Winton for his C<MD5> module.
 
+This library is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+    Copyright 1998-2001,2003 Gisle Aas.
+    Copyright 1995-1996 Neil Winton.
+
 =cut