From: Nicholas Clark <nick@ccl4.org>
Date: Sat, 27 Dec 2003 17:24:27 +0000 (+0000)
Subject: Assimilate Digest 1.05
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=e19eb3c1189f80471d9e8bc1bac9bafb84e853ef;p=p5sagit%2Fp5-mst-13.2.git

Assimilate Digest 1.05

p4raw-id: //depot/perl@21973
---

diff --git a/lib/Digest.pm b/lib/Digest.pm
index c0e9cc1..9353db1 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
diff --git a/lib/Digest/t/digest.t b/lib/Digest/t/digest.t
index fbc2dac..c5da8f0 100644
--- a/lib/Digest/t/digest.t
+++ b/lib/Digest/t/digest.t
@@ -2,22 +2,35 @@ print "1..3\n";
 
 use Digest;
 
-my $hexdigest = "900150983cd24fb0d6963f7d28e17f72"; # ASCII
+{
+    package Digest::Dummy;
+    use vars qw($VERSION @ISA);
+    $VERSION = 1;
 
-if (ord('A') == 193) { # EBCDIC
-    $hexdigest = "fe4ea0d98f9cd8d1d27f102a93cb0bb0"; # IBM-1047
+    require Digest::base;
+    @ISA = qw(Digest::base);
+
+    sub new {
+	my $class = shift;
+	my $d = shift || "ooo";
+	bless { d => $d }, $class;
+    }
+    sub add {}
+    sub digest { shift->{d} }
 }
 
-print "not " unless Digest->MD5->add("abc")->hexdigest eq $hexdigest;
+my $d;
+$d = Digest->new("Dummy");
+print "not " unless $d->digest eq "ooo";
 print "ok 1\n";
 
-print "not " unless Digest->MD5->add("abc")->hexdigest eq $hexdigest;
+$d = Digest->Dummy;
+print "not " unless $d->digest eq "ooo";
 print "ok 2\n";
 
-eval {
-    # Not yet EBCDICified.
-    print "not " unless Digest->new("HMAC-MD5" => "Jefe")->add("what do ya want for nothing?")->hexdigest eq "750c783e6ab0b503eaa86e310a5db738";
-    print "ok 3\n";
-};
-print "ok 3\n" if $@ && $@ =~ /^Can't locate/;
+$Digest::MMAP{"Dummy-24"} = [["NotThere"], "NotThereEither", ["Digest::Dummy", 24]];
+$d = Digest->new("Dummy-24");
+print "not " unless $d->digest eq "24";
+print "ok 3\n";
+