X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDigest.pm;h=98102ae6bfac1e049d11de5a936d31737ae6173f;hb=47a7661deb880b9c5c3ea4517c4908096fdff41f;hp=f9a3930d736d54a7beb41e7a9dfcdba5de4b9655;hpb=897ff129fe66a34d2316b4c99eea687601add373;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/Digest.pm b/lib/Digest.pm index f9a3930..98102ae 100644 --- a/lib/Digest.pm +++ b/lib/Digest.pm @@ -3,15 +3,19 @@ package Digest; use strict; use vars qw($VERSION %MMAP $AUTOLOAD); -$VERSION = "1.06"; +$VERSION = "1.15"; %MMAP = ( "SHA-1" => ["Digest::SHA1", ["Digest::SHA", 1], ["Digest::SHA2", 1]], + "SHA-224" => [["Digest::SHA", 224]], "SHA-256" => [["Digest::SHA", 256], ["Digest::SHA2", 256]], "SHA-384" => [["Digest::SHA", 384], ["Digest::SHA2", 384]], "SHA-512" => [["Digest::SHA", 512], ["Digest::SHA2", 512]], "HMAC-MD5" => "Digest::HMAC_MD5", "HMAC-SHA-1" => "Digest::HMAC_SHA1", + "CRC-16" => [["Digest::CRC", type => "crc16"]], + "CRC-32" => [["Digest::CRC", type => "crc32"]], + "CRC-CCITT" => [["Digest::CRC", type => "crcccitt"]], ); sub new @@ -76,11 +80,18 @@ bytes or bits. An important property of the digest algorithms is that the digest is I to change if the message change in some way. Another -property is that digest functions are one-way functions, i.e. it +property is that digest functions are one-way functions, that is it should be I to find a message that correspond to some given digest. Algorithms differ in how "likely" and how "hard", as well as how efficient they are to compute. +Note that the properties of the algorithms change over time, as the +algorithms are analyzed and machines grow faster. If your application +for instance depends on it being "impossible" to generate the same +digest for a different message it is wise to make it easy to plug in +stronger algorithms as the one used grow weaker. Using the interface +documented here should make it easy to change algorithms later. + All C modules provide the same programming interface. A functional interface for simple use, as well as an object oriented interface that can handle messages of arbitrary length and which can @@ -156,10 +167,26 @@ a reference to the copy. This is just an alias for $ctx->new. -=item $ctx->add( $data, ... ) +=item $ctx->add( $data ) + +=item $ctx->add( $chunk1, $chunk2, ... ) + +The string value of the $data provided as argument is appended to the +message we calculate the digest for. The return value is the $ctx +object itself. + +If more arguments are provided then they are all appended to the +message, thus all these lines will have the same effect on the state +of the $ctx object: -The $data provided as argument are appended to the message we -calculate the digest for. The return value is the $ctx object itself. + $ctx->add("a"); $ctx->add("b"); $ctx->add("c"); + $ctx->add("a")->add("b")->add("c"); + $ctx->add("a", "b", "c"); + $ctx->add("abc"); + +Most algorithms are only defined for strings of bytes and this method +might therefore croak if the provided arguments contain chars with +ordinal number above 255. =item $ctx->addfile( $io_handle ) @@ -167,29 +194,42 @@ 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. +The addfile() method will croak() if it fails reading data for some +reason. If it croaks it is unpredictable what the state of the $ctx +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 $ctx object if this occurs. + +In most cases you want to make sure that the $io_handle is in +"binmode" before you pass it as argument to the addfile() method. + =item $ctx->add_bits( $data, $nbits ) =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. +The add_bits() method is an alternative to add() that allow partial +bytes to be appended to the message. Most users should just ignore +this method as partial bytes is very unlikely to be of any practical +use. The two argument form of add_bits() will add the first $nbits bits -from data. For the last potentially partial byte only the high order +from $data. For the last potentially partial byte only the high order C<< $nbits % 8 >> bits are used. If $nbits is greater than C<< length($data) * 8 >>, then this method would do the same as C<< -$ctx->add($data) >>, i.e. $nbits is silently ignored. +$ctx->add($data) >>. The one argument form of add_bits() takes a $bitstring of "1" and "0" chars as argument. It's a shorthand for C<< $ctx->add_bits(pack("B*", $bitstring), length($bitstring)) >>. +The return value is the $ctx object itself. + This example shows two calls that should have the same effect: $ctx->add_bits("111100001010"); $ctx->add_bits("\xF0\xA0", 12); -Most digest algorithms are byte based. For those it is not possible +Most digest algorithms are byte based and for these it is not possible to add bits that are not a multiple of 8, and the add_bits() method will croak if you try. @@ -201,7 +241,7 @@ Note that the C operation is effectively a destructive, read-once operation. Once it has been performed, the $ctx object is automatically C and can be used to calculate another digest value. Call $ctx->clone->digest if you want to calculate the digest -without reseting the digest state. +without resetting the digest state. =item $ctx->hexdigest @@ -220,38 +260,45 @@ 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 + Algorithm Size Implementation MB/s + + MD4 128 Digest::MD4 v1.3 165.0 + MD5 128 Digest::MD5 v2.33 98.8 + SHA-256 256 Digest::SHA2 v1.1.0 66.7 + SHA-1 160 Digest::SHA v4.3.1 58.9 + SHA-1 160 Digest::SHA1 v2.10 48.8 + SHA-256 256 Digest::SHA v4.3.1 41.3 + Haval-256 256 Digest::Haval256 v1.0.4 39.8 + SHA-384 384 Digest::SHA2 v1.1.0 19.6 + SHA-512 512 Digest::SHA2 v1.1.0 19.3 + SHA-384 384 Digest::SHA v4.3.1 19.2 + SHA-512 512 Digest::SHA v4.3.1 19.2 + Whirlpool 512 Digest::Whirlpool v1.0.2 13.0 + MD2 128 Digest::MD2 v2.03 9.5 + + Adler-32 32 Digest::Adler32 v0.03 1.3 + CRC-16 16 Digest::CRC v0.05 1.1 + CRC-32 32 Digest::CRC v0.05 1.1 + MD5 128 Digest::Perl::MD5 v1.5 1.0 + CRC-CCITT 16 Digest::CRC v0.05 0.8 + +These numbers was achieved Apr 2004 with ActivePerl-5.8.3 running +under Linux on a P4 2.8 GHz CPU. The last 5 entries differ by being pure perl implementations of the algorithms, which explains why they are so slow. =head1 SEE ALSO -L, L, L, L, L, L, L, L, L, L +L, L, L, +L, L, L, L, +L, L, L, L New digest implementations should consider subclassing from L. L +http://en.wikipedia.org/wiki/Cryptographic_hash_function + =head1 AUTHOR Gisle Aas @@ -262,7 +309,7 @@ developed by Neil Winton for his C 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-2004 Gisle Aas. - Copyright 1995-1996 Neil Winton. + Copyright 1998-2006 Gisle Aas. + Copyright 1995,1996 Neil Winton. =cut