1Digest(3)             User Contributed Perl Documentation            Digest(3)
2
3
4

NAME

6       Digest - Modules that calculate message digests
7

SYNOPSIS

9         $md5  = Digest->new("MD5");
10         $sha1 = Digest->new("SHA-1");
11         $sha256 = Digest->new("SHA-256");
12         $sha384 = Digest->new("SHA-384");
13         $sha512 = Digest->new("SHA-512");
14
15         $hmac = Digest->HMAC_MD5($key);
16

DESCRIPTION

18       The "Digest::" modules calculate digests, also called "fingerprints" or
19       "hashes", of some data, called a message.  The digest is (usually) some
20       small/fixed size string.  The actual size of the digest depend of the
21       algorithm used.  The message is simply a sequence of arbitrary bytes or
22       bits.
23
24       An important property of the digest algorithms is that the digest is
25       likely to change if the message change in some way.  Another property
26       is that digest functions are one-way functions, that is it should be
27       hard to find a message that correspond to some given digest.
28       Algorithms differ in how "likely" and how "hard", as well as how
29       efficient they are to compute.
30
31       Note that the properties of the algorithms change over time, as the
32       algorithms are analyzed and machines grow faster.  If your application
33       for instance depends on it being "impossible" to generate the same
34       digest for a different message it is wise to make it easy to plug in
35       stronger algorithms as the one used grow weaker.  Using the interface
36       documented here should make it easy to change algorithms later.
37
38       All "Digest::" modules provide the same programming interface.  A
39       functional interface for simple use, as well as an object oriented
40       interface that can handle messages of arbitrary length and which can
41       read files directly.
42
43       The digest can be delivered in three formats:
44
45       binary  This is the most compact form, but it is not well suited for
46               printing or embedding in places that can't handle arbitrary
47               data.
48
49       hex     A twice as long string of lowercase hexadecimal digits.
50
51       base64  A string of portable printable characters.  This is the base64
52               encoded representation of the digest with any trailing padding
53               removed.  The string will be about 30% longer than the binary
54               version.  MIME::Base64 tells you more about this encoding.
55
56       The functional interface is simply importable functions with the same
57       name as the algorithm.  The functions take the message as argument and
58       return the digest.  Example:
59
60         use Digest::MD5 qw(md5);
61         $digest = md5($message);
62
63       There are also versions of the functions with "_hex" or "_base64"
64       appended to the name, which returns the digest in the indicated form.
65

OO INTERFACE

67       The following methods are available for all "Digest::" modules:
68
69       $ctx = Digest->XXX($arg,...)
70       $ctx = Digest->new(XXX => $arg,...)
71       $ctx = Digest::XXX->new($arg,...)
72           The constructor returns some object that encapsulate the state of
73           the message-digest algorithm.  You can add data to the object and
74           finally ask for the digest.  The "XXX" should of course be replaced
75           by the proper name of the digest algorithm you want to use.
76
77           The two first forms are simply syntactic sugar which automatically
78           load the right module on first use.  The second form allow you to
79           use algorithm names which contains letters which are not legal perl
80           identifiers, e.g. "SHA-1".  If no implementation for the given
81           algorithm can be found, then an exception is raised.
82
83           To know what arguments (if any) the constructor takes (the
84           "$args,..." above) consult the docs for the specific digest
85           implementation.
86
87           If new() is called as an instance method (i.e. $ctx->new) it will
88           just reset the state the object to the state of a newly created
89           object.  No new object is created in this case, and the return
90           value is the reference to the object (i.e. $ctx).
91
92       $other_ctx = $ctx->clone
93           The clone method creates a copy of the digest state object and
94           returns a reference to the copy.
95
96       $ctx->reset
97           This is just an alias for $ctx->new.
98
99       $ctx->add( $data )
100       $ctx->add( $chunk1, $chunk2, ... )
101           The string value of the $data provided as argument is appended to
102           the message we calculate the digest for.  The return value is the
103           $ctx object itself.
104
105           If more arguments are provided then they are all appended to the
106           message, thus all these lines will have the same effect on the
107           state of the $ctx object:
108
109             $ctx->add("a"); $ctx->add("b"); $ctx->add("c");
110             $ctx->add("a")->add("b")->add("c");
111             $ctx->add("a", "b", "c");
112             $ctx->add("abc");
113
114           Most algorithms are only defined for strings of bytes and this
115           method might therefore croak if the provided arguments contain
116           chars with ordinal number above 255.
117
118       $ctx->addfile( $io_handle )
119           The $io_handle is read until EOF and the content is appended to the
120           message we calculate the digest for.  The return value is the $ctx
121           object itself.
122
123           The addfile() method will croak() if it fails reading data for some
124           reason.  If it croaks it is unpredictable what the state of the
125           $ctx object will be in. The addfile() method might have been able
126           to read the file partially before it failed.  It is probably wise
127           to discard or reset the $ctx object if this occurs.
128
129           In most cases you want to make sure that the $io_handle is in
130           "binmode" before you pass it as argument to the addfile() method.
131
132       $ctx->add_bits( $data, $nbits )
133       $ctx->add_bits( $bitstring )
134           The add_bits() method is an alternative to add() that allow partial
135           bytes to be appended to the message.  Most users can just ignore
136           this method since typical applications involve only whole-byte
137           data.
138
139           The two argument form of add_bits() will add the first $nbits bits
140           from $data.  For the last potentially partial byte only the high
141           order "$nbits % 8" bits are used.  If $nbits is greater than
142           "length($data) * 8", then this method would do the same as
143           "$ctx->add($data)".
144
145           The one argument form of add_bits() takes a $bitstring of "1" and
146           "0" chars as argument.  It's a shorthand for
147           "$ctx->add_bits(pack("B*", $bitstring), length($bitstring))".
148
149           The return value is the $ctx object itself.
150
151           This example shows two calls that should have the same effect:
152
153              $ctx->add_bits("111100001010");
154              $ctx->add_bits("\xF0\xA0", 12);
155
156           Most digest algorithms are byte based and for these it is not
157           possible to add bits that are not a multiple of 8, and the
158           add_bits() method will croak if you try.
159
160       $ctx->digest
161           Return the binary digest for the message.
162
163           Note that the "digest" operation is effectively a destructive,
164           read-once operation. Once it has been performed, the $ctx object is
165           automatically "reset" and can be used to calculate another digest
166           value.  Call $ctx->clone->digest if you want to calculate the
167           digest without resetting the digest state.
168
169       $ctx->hexdigest
170           Same as $ctx->digest, but will return the digest in hexadecimal
171           form.
172
173       $ctx->b64digest
174           Same as $ctx->digest, but will return the digest as a base64
175           encoded string without padding.
176
177       $ctx->base64_padded_digest
178           Same as $ctx->digest, but will return the digest as a base64
179           encoded string.
180

Digest speed

182       This table should give some indication on the relative speed of
183       different algorithms.  It is sorted by throughput based on a benchmark
184       done with of some implementations of this API:
185
186        Algorithm      Size    Implementation                  MB/s
187
188        MD4            128     Digest::MD4 v1.3               165.0
189        MD5            128     Digest::MD5 v2.33               98.8
190        SHA-256        256     Digest::SHA2 v1.1.0             66.7
191        SHA-1          160     Digest::SHA v4.3.1              58.9
192        SHA-1          160     Digest::SHA1 v2.10              48.8
193        SHA-256        256     Digest::SHA v4.3.1              41.3
194        Haval-256      256     Digest::Haval256 v1.0.4         39.8
195        SHA-384        384     Digest::SHA2 v1.1.0             19.6
196        SHA-512        512     Digest::SHA2 v1.1.0             19.3
197        SHA-384        384     Digest::SHA v4.3.1              19.2
198        SHA-512        512     Digest::SHA v4.3.1              19.2
199        Whirlpool      512     Digest::Whirlpool v1.0.2        13.0
200        MD2            128     Digest::MD2 v2.03                9.5
201
202        Adler-32        32     Digest::Adler32 v0.03            1.3
203        CRC-16          16     Digest::CRC v0.05                1.1
204        CRC-32          32     Digest::CRC v0.05                1.1
205        MD5            128     Digest::Perl::MD5 v1.5           1.0
206        CRC-CCITT       16     Digest::CRC v0.05                0.8
207
208       These numbers was achieved Apr 2004 with ActivePerl-5.8.3 running under
209       Linux on a P4 2.8 GHz CPU.  The last 5 entries differ by being pure
210       perl implementations of the algorithms, which explains why they are so
211       slow.
212

SEE ALSO

214       Digest::Adler32, Digest::CRC, Digest::Haval256, Digest::HMAC,
215       Digest::MD2, Digest::MD4, Digest::MD5, Digest::SHA, Digest::SHA1,
216       Digest::SHA2, Digest::Whirlpool
217
218       New digest implementations should consider subclassing from
219       Digest::base.
220
221       MIME::Base64
222
223       http://en.wikipedia.org/wiki/Cryptographic_hash_function
224

AUTHOR

226       Gisle Aas <gisle@aas.no>
227
228       The "Digest::" interface is based on the interface originally developed
229       by Neil Winton for his "MD5" module.
230
231       This library is free software; you can redistribute it and/or modify it
232       under the same terms as Perl itself.
233
234           Copyright 1998-2006 Gisle Aas.
235           Copyright 1995,1996 Neil Winton.
236
237
238
239perl v5.32.1                      2021-01-27                         Digest(3)
Impressum