| 1 | package Digest; |
| 2 | |
| 3 | use strict; |
| 4 | use vars qw($VERSION %MMAP $AUTOLOAD); |
| 5 | |
| 6 | $VERSION = "1.00"; |
| 7 | |
| 8 | %MMAP = ( |
| 9 | "SHA-1" => "Digest::SHA1", |
| 10 | "HMAC-MD5" => "Digest::HMAC_MD5", |
| 11 | "HMAC-SHA-1" => "Digest::HMAC_SHA1", |
| 12 | ); |
| 13 | |
| 14 | sub new |
| 15 | { |
| 16 | shift; # class ignored |
| 17 | my $algorithm = shift; |
| 18 | my $class = $MMAP{$algorithm} || "Digest::$algorithm"; |
| 19 | no strict 'refs'; |
| 20 | unless (exists ${"$class\::"}{"VERSION"}) { |
| 21 | eval "require $class"; |
| 22 | die $@ if $@; |
| 23 | } |
| 24 | $class->new(@_); |
| 25 | } |
| 26 | |
| 27 | sub AUTOLOAD |
| 28 | { |
| 29 | my $class = shift; |
| 30 | my $algorithm = substr($AUTOLOAD, rindex($AUTOLOAD, '::')+2); |
| 31 | $class->new($algorithm, @_); |
| 32 | } |
| 33 | |
| 34 | 1; |
| 35 | |
| 36 | __END__ |
| 37 | |
| 38 | =head1 NAME |
| 39 | |
| 40 | Digest:: - Modules that calculate message digests |
| 41 | |
| 42 | =head1 SYNOPSIS |
| 43 | |
| 44 | $md2 = Digest->MD2; |
| 45 | $md5 = Digest->MD5; |
| 46 | |
| 47 | $sha1 = Digest->SHA1; |
| 48 | $sha1 = Digest->new("SHA-1"); |
| 49 | |
| 50 | $hmac = Digest->HMAC_MD5($key); |
| 51 | |
| 52 | =head1 DESCRIPTION |
| 53 | |
| 54 | The C<Digest::> modules calculate digests, also called "fingerprints" |
| 55 | or "hashes", of some data, called a message. The digest is (usually) |
| 56 | some small/fixed size string. The actual size of the digest depend of |
| 57 | the algorithm used. The message is simply a sequence of arbitrary |
| 58 | bytes. |
| 59 | |
| 60 | An important property of the digest algorithms is that the digest is |
| 61 | I<likely> to change if the message change in some way. Another |
| 62 | property is that digest functions are one-way functions, i.e. it |
| 63 | should be I<hard> to find a message that correspond to some given |
| 64 | digest. Algorithms differ in how "likely" and how "hard", as well as |
| 65 | how efficient they are to compute. |
| 66 | |
| 67 | All C<Digest::> modules provide the same programming interface. A |
| 68 | functional interface for simple use, as well as an object oriented |
| 69 | interface that can handle messages of arbitrary length and which can |
| 70 | read files directly. |
| 71 | |
| 72 | The digest can be delivered in three formats: |
| 73 | |
| 74 | =over 8 |
| 75 | |
| 76 | =item I<binary> |
| 77 | |
| 78 | This is the most compact form, but it is not well suited for printing |
| 79 | or embedding in places that can't handle arbitrary data. |
| 80 | |
| 81 | =item I<hex> |
| 82 | |
| 83 | A twice as long string of (lowercase) hexadecimal digits. |
| 84 | |
| 85 | =item I<base64> |
| 86 | |
| 87 | A string of portable printable characters. This is the base64 encoded |
| 88 | representation of the digest with any trailing padding removed. The |
| 89 | string will be about 30% longer than the binary version. |
| 90 | L<MIME::Base64> tells you more about this encoding. |
| 91 | |
| 92 | =back |
| 93 | |
| 94 | |
| 95 | The functional interface is simply importable functions with the same |
| 96 | name as the algorithm. The functions take the message as argument and |
| 97 | return the digest. Example: |
| 98 | |
| 99 | use Digest::MD5 qw(md5); |
| 100 | $digest = md5($message); |
| 101 | |
| 102 | There are also versions of the functions with "_hex" or "_base64" |
| 103 | appended to the name, which returns the digest in the indicated form. |
| 104 | |
| 105 | =head1 OO INTERFACE |
| 106 | |
| 107 | The following methods are available for all C<Digest::> modules: |
| 108 | |
| 109 | =over 4 |
| 110 | |
| 111 | =item $ctx = Digest->XXX($arg,...) |
| 112 | |
| 113 | =item $ctx = Digest->new(XXX => $arg,...) |
| 114 | |
| 115 | =item $ctx = Digest::XXX->new($arg,...) |
| 116 | |
| 117 | The constructor returns some object that encapsulate the state of the |
| 118 | message-digest algorithm. You can add data to the object and finally |
| 119 | ask for the digest. The "XXX" should of course be replaced by the proper |
| 120 | name of the digest algorithm you want to use. |
| 121 | |
| 122 | The two first forms are simply syntactic sugar which automatically |
| 123 | load the right module on first use. The second form allow you to use |
| 124 | algorithm names which contains letters which are not legal perl |
| 125 | identifiers, e.g. "SHA-1". |
| 126 | |
| 127 | If new() is called as a instance method (i.e. $ctx->new) it will just |
| 128 | reset the state the object to the state of a newly created object. No |
| 129 | new object is created in this case, and the return value is the |
| 130 | reference to the object (i.e. $ctx). |
| 131 | |
| 132 | =item $ctx->reset |
| 133 | |
| 134 | This is just an alias for $ctx->new. |
| 135 | |
| 136 | =item $ctx->add($data,...) |
| 137 | |
| 138 | The $data provided as argument are appended to the message we |
| 139 | calculate the digest for. The return value is the $ctx object itself. |
| 140 | |
| 141 | =item $ctx->addfile($io_handle) |
| 142 | |
| 143 | The $io_handle is read until EOF and the content is appended to the |
| 144 | message we calculate the digest for. The return value is the $ctx |
| 145 | object itself. |
| 146 | |
| 147 | =item $ctx->digest |
| 148 | |
| 149 | Return the binary digest for the message. |
| 150 | |
| 151 | Note that the C<digest> operation is effectively a destructive, |
| 152 | read-once operation. Once it has been performed, the $ctx object is |
| 153 | automatically C<reset> and can be used to calculate another digest |
| 154 | value. |
| 155 | |
| 156 | =item $ctx->hexdigest |
| 157 | |
| 158 | Same as $ctx->digest, but will return the digest in hexadecimal form. |
| 159 | |
| 160 | =item $ctx->b64digest |
| 161 | |
| 162 | Same as $ctx->digest, but will return the digest as a base64 encoded |
| 163 | string. |
| 164 | |
| 165 | =back |
| 166 | |
| 167 | =head1 SEE ALSO |
| 168 | |
| 169 | L<Digest::MD5>, L<Digest::SHA1>, L<Digest::HMAC>, L<Digest::MD2> |
| 170 | |
| 171 | L<MIME::Base64> |
| 172 | |
| 173 | =head1 AUTHOR |
| 174 | |
| 175 | Gisle Aas <gisle@aas.no> |
| 176 | |
| 177 | The C<Digest::> interface is based on the interface originally |
| 178 | developed by Neil Winton for his C<MD5> module. |
| 179 | |
| 180 | =cut |