mingw/html/lib/Digest.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Digest - Modules that calculate message digests</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Digest - Modules that calculate message digests</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#oo_interface">OO INTERFACE</a></li>
  26         <li><a href="#digest_speed">Digest speed</a></li>
  27         <li><a href="#see_also">SEE ALSO</a></li>
  28         <li><a href="#author">AUTHOR</a></li>
  29 </ul>
  30 <!-- INDEX END -->
  31
  32 <hr />
  33 <p>
  34 </p>
  35 <h1><a name="name">NAME</a></h1>
  36 <p>Digest - Modules that calculate message digests</p>
  37 <p>
  38 </p>
  39 <hr />
  40 <h1><a name="synopsis">SYNOPSIS</a></h1>
  41 <pre>
  42   $md5  = Digest-&gt;new(&quot;MD5&quot;);
  43   $sha1 = Digest-&gt;new(&quot;SHA-1&quot;);
  44   $sha256 = Digest-&gt;new(&quot;SHA-256&quot;);
  45   $sha384 = Digest-&gt;new(&quot;SHA-384&quot;);
  46   $sha512 = Digest-&gt;new(&quot;SHA-512&quot;);</pre>
  47 <pre>
  48   $hmac = Digest-&gt;HMAC_MD5($key);</pre>
  49 <p>
  50 </p>
  51 <hr />
  52 <h1><a name="description">DESCRIPTION</a></h1>
  53 <p>The <code>Digest::</code> modules calculate digests, also called ``fingerprints''
  54 or ``hashes'', of some data, called a message.  The digest is (usually)
  55 some small/fixed size string.  The actual size of the digest depend of
  56 the algorithm used.  The message is simply a sequence of arbitrary
  57 bytes or bits.</p>
  58 <p>An important property of the digest algorithms is that the digest is
  59 <em>likely</em> to change if the message change in some way.  Another
  60 property is that digest functions are one-way functions, that is it
  61 should be <em>hard</em> to find a message that correspond to some given
  62 digest.  Algorithms differ in how ``likely'' and how ``hard'', as well as
  63 how efficient they are to compute.</p>
  64 <p>Note that the properties of the algorithms change over time, as the
  65 algorithms are analyzed and machines grow faster.  If your application
  66 for instance depends on it being ``impossible'' to generate the same
  67 digest for a different message it is wise to make it easy to plug in
  68 stronger algorithms as the one used grow weaker.  Using the interface
  69 documented here should make it easy to change algorithms later.</p>
  70 <p>All <code>Digest::</code> modules provide the same programming interface.  A
  71 functional interface for simple use, as well as an object oriented
  72 interface that can handle messages of arbitrary length and which can
  73 read files directly.</p>
  74 <p>The digest can be delivered in three formats:</p>
  75 <dl>
  76 <dt><strong><a name="item_binary"><em>binary</em></a></strong>
  77
  78 <dd>
  79 <p>This is the most compact form, but it is not well suited for printing
  80 or embedding in places that can't handle arbitrary data.</p>
  81 </dd>
  82 </li>
  83 <dt><strong><a name="item_hex"><em>hex</em></a></strong>
  84
  85 <dd>
  86 <p>A twice as long string of lowercase hexadecimal digits.</p>
  87 </dd>
  88 </li>
  89 <dt><strong><a name="item_base64"><em>base64</em></a></strong>
  90
  91 <dd>
  92 <p>A string of portable printable characters.  This is the base64 encoded
  93 representation of the digest with any trailing padding removed.  The
  94 string will be about 30% longer than the binary version.
  95 <a href="file://C|\msysgit\mingw\html/lib/MIME/Base64.html">the MIME::Base64 manpage</a> tells you more about this encoding.</p>
  96 </dd>
  97 </li>
  98 </dl>
  99 <p>The functional interface is simply importable functions with the same
 100 name as the algorithm.  The functions take the message as argument and
 101 return the digest.  Example:</p>
 102 <pre>
 103   use Digest::MD5 qw(md5);
 104   $digest = md5($message);</pre>
 105 <p>There are also versions of the functions with ``_hex'' or ``_base64''
 106 appended to the name, which returns the digest in the indicated form.</p>
 107 <p>
 108 </p>
 109 <hr />
 110 <h1><a name="oo_interface">OO INTERFACE</a></h1>
 111 <p>The following methods are available for all <code>Digest::</code> modules:</p>
 112 <dl>
 113 <dt><strong><a name="item_xxx">$ctx = Digest-&gt;<code>XXX($arg,...)</code></a></strong>
 114
 115 <dt><strong><a name="item_new">$ctx = Digest-&gt;new(XXX =&gt; $arg,...)</a></strong>
 116
 117 <dt><strong>$ctx = Digest::XXX-&gt;<code>new($arg,...)</code></strong>
 118
 119 <dd>
 120 <p>The constructor returns some object that encapsulate the state of the
 121 message-digest algorithm.  You can add data to the object and finally
 122 ask for the digest.  The ``XXX'' should of course be replaced by the proper
 123 name of the digest algorithm you want to use.</p>
 124 </dd>
 125 <dd>
 126 <p>The two first forms are simply syntactic sugar which automatically
 127 load the right module on first use.  The second form allow you to use
 128 algorithm names which contains letters which are not legal perl
 129 identifiers, e.g. ``SHA-1''.  If no implementation for the given algorithm
 130 can be found, then an exception is raised.</p>
 131 </dd>
 132 <dd>
 133 <p>If <a href="#item_new"><code>new()</code></a> is called as an instance method (i.e. $ctx-&gt;new) it will just
 134 reset the state the object to the state of a newly created object.  No
 135 new object is created in this case, and the return value is the
 136 reference to the object (i.e. $ctx).</p>
 137 </dd>
 138 </li>
 139 <dt><strong><a name="item_clone">$other_ctx = $ctx-&gt;clone</a></strong>
 140
 141 <dd>
 142 <p>The clone method creates a copy of the digest state object and returns
 143 a reference to the copy.</p>
 144 </dd>
 145 </li>
 146 <dt><strong><a name="item_reset">$ctx-&gt;reset</a></strong>
 147
 148 <dd>
 149 <p>This is just an alias for $ctx-&gt;new.</p>
 150 </dd>
 151 </li>
 152 <dt><strong><a name="item_add">$ctx-&gt;add( $data, ... )</a></strong>
 153
 154 <dd>
 155 <p>The $data provided as argument are appended to the message we
 156 calculate the digest for.  The return value is the $ctx object itself.</p>
 157 </dd>
 158 </li>
 159 <dt><strong><a name="item_addfile">$ctx-&gt;addfile( $io_handle )</a></strong>
 160
 161 <dd>
 162 <p>The $io_handle is read until EOF and the content is appended to the
 163 message we calculate the digest for.  The return value is the $ctx
 164 object itself.</p>
 165 </dd>
 166 </li>
 167 <dt><strong><a name="item_add_bits">$ctx-&gt;add_bits( $data, $nbits )</a></strong>
 168
 169 <dt><strong>$ctx-&gt;add_bits( $bitstring )</strong>
 170
 171 <dd>
 172 <p>The bits provided are appended to the message we calculate the digest
 173 for.  The return value is the $ctx object itself.</p>
 174 </dd>
 175 <dd>
 176 <p>The two argument form of <a href="#item_add_bits"><code>add_bits()</code></a> will add the first $nbits bits
 177 from data.  For the last potentially partial byte only the high order
 178 <code>$nbits % 8</code> bits are used.  If $nbits is greater than <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_length"><code>&lt;
 179 length($data) * 8 </code></a>&gt;, then this method would do the same as <code>&lt;
 180 $ctx-</code><a href="#item_add"><code>add($data)</code></a> &gt;&gt;, that is $nbits is silently ignored.</p>
 181 </dd>
 182 <dd>
 183 <p>The one argument form of <a href="#item_add_bits"><code>add_bits()</code></a> takes a $bitstring of ``1'' and ``0''
 184 chars as argument.  It's a shorthand for <a href="#item_add_bits"><code>$ctx-&gt;add_bits(pack(&quot;B*&quot;,
 185 $bitstring), length($bitstring))</code></a>.</p>
 186 </dd>
 187 <dd>
 188 <p>This example shows two calls that should have the same effect:</p>
 189 </dd>
 190 <dd>
 191 <pre>
 192    $ctx-&gt;add_bits(&quot;111100001010&quot;);
 193    $ctx-&gt;add_bits(&quot;\xF0\xA0&quot;, 12);</pre>
 194 </dd>
 195 <dd>
 196 <p>Most digest algorithms are byte based.  For those it is not possible
 197 to add bits that are not a multiple of 8, and the <a href="#item_add_bits"><code>add_bits()</code></a> method
 198 will croak if you try.</p>
 199 </dd>
 200 </li>
 201 <dt><strong><a name="item_digest">$ctx-&gt;digest</a></strong>
 202
 203 <dd>
 204 <p>Return the binary digest for the message.</p>
 205 </dd>
 206 <dd>
 207 <p>Note that the <a href="#item_digest"><code>digest</code></a> operation is effectively a destructive,
 208 read-once operation. Once it has been performed, the $ctx object is
 209 automatically <a href="#item_reset"><code>reset</code></a> and can be used to calculate another digest
 210 value.  Call $ctx-&gt;clone-&gt;digest if you want to calculate the digest
 211 without reseting the digest state.</p>
 212 </dd>
 213 </li>
 214 <dt><strong><a name="item_hexdigest">$ctx-&gt;hexdigest</a></strong>
 215
 216 <dd>
 217 <p>Same as $ctx-&gt;digest, but will return the digest in hexadecimal form.</p>
 218 </dd>
 219 </li>
 220 <dt><strong><a name="item_b64digest">$ctx-&gt;b64digest</a></strong>
 221
 222 <dd>
 223 <p>Same as $ctx-&gt;digest, but will return the digest as a base64 encoded
 224 string.</p>
 225 </dd>
 226 </li>
 227 </dl>
 228 <p>
 229 </p>
 230 <hr />
 231 <h1><a name="digest_speed">Digest speed</a></h1>
 232 <p>This table should give some indication on the relative speed of
 233 different algorithms.  It is sorted by throughput based on a benchmark
 234 done with of some implementations of this API:</p>
 235 <pre>
 236  Algorithm      Size    Implementation                  MB/s</pre>
 237 <pre>
 238  MD4            128     Digest::MD4 v1.3               165.0
 239  MD5            128     Digest::MD5 v2.33               98.8
 240  SHA-256        256     Digest::SHA2 v1.1.0             66.7
 241  SHA-1          160     Digest::SHA v4.3.1              58.9
 242  SHA-1          160     Digest::SHA1 v2.10              48.8
 243  SHA-256        256     Digest::SHA v4.3.1              41.3
 244  Haval-256      256     Digest::Haval256 v1.0.4         39.8
 245  SHA-384        384     Digest::SHA2 v1.1.0             19.6
 246  SHA-512        512     Digest::SHA2 v1.1.0             19.3
 247  SHA-384        384     Digest::SHA v4.3.1              19.2
 248  SHA-512        512     Digest::SHA v4.3.1              19.2
 249  Whirlpool      512     Digest::Whirlpool v1.0.2        13.0
 250  MD2            128     Digest::MD2 v2.03                9.5</pre>
 251 <pre>
 252  Adler-32        32     Digest::Adler32 v0.03            1.3
 253  CRC-16          16     Digest::CRC v0.05                1.1
 254  CRC-32          32     Digest::CRC v0.05                1.1
 255  MD5            128     Digest::Perl::MD5 v1.5           1.0
 256  CRC-CCITT       16     Digest::CRC v0.05                0.8</pre>
 257 <p>These numbers was achieved Apr 2004 with ActivePerl-5.8.3 running
 258 under Linux on a P4 2.8 GHz CPU.  The last 5 entries differ by being
 259 pure perl implementations of the algorithms, which explains why they
 260 are so slow.</p>
 261 <p>
 262 </p>
 263 <hr />
 264 <h1><a name="see_also">SEE ALSO</a></h1>
 265 <p><a href="file://C|\msysgit\mingw\html/Digest/Adler32.html">the Digest::Adler32 manpage</a>, <a href="file://C|\msysgit\mingw\html/Digest/CRC.html">the Digest::CRC manpage</a>, <a href="file://C|\msysgit\mingw\html/Digest/Haval256.html">the Digest::Haval256 manpage</a>,
 266 <a href="file://C|\msysgit\mingw\html/Digest/HMAC.html">the Digest::HMAC manpage</a>, <a href="file://C|\msysgit\mingw\html/Digest/MD2.html">the Digest::MD2 manpage</a>, <a href="file://C|\msysgit\mingw\html/Digest/MD4.html">the Digest::MD4 manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/Digest/MD5.html">the Digest::MD5 manpage</a>,
 267 <a href="file://C|\msysgit\mingw\html/Digest/SHA.html">the Digest::SHA manpage</a>, <a href="file://C|\msysgit\mingw\html/Digest/SHA1.html">the Digest::SHA1 manpage</a>, <a href="file://C|\msysgit\mingw\html/Digest/SHA2.html">the Digest::SHA2 manpage</a>, <a href="file://C|\msysgit\mingw\html/Digest/Whirlpool.html">the Digest::Whirlpool manpage</a></p>
 268 <p>New digest implementations should consider subclassing from <a href="file://C|\msysgit\mingw\html/lib/Digest/base.html">the Digest::base manpage</a>.</p>
 269 <p><a href="file://C|\msysgit\mingw\html/lib/MIME/Base64.html">the MIME::Base64 manpage</a></p>
 270 <p>
 271 </p>
 272 <hr />
 273 <h1><a name="author">AUTHOR</a></h1>
 274 <p>Gisle Aas &lt;<a href="mailto:gisle@aas.no">gisle@aas.no</a>&gt;</p>
 275 <p>The <code>Digest::</code> interface is based on the interface originally
 276 developed by Neil Winton for his <code>MD5</code> module.</p>
 277 <p>This library is free software; you can redistribute it and/or
 278 modify it under the same terms as Perl itself.</p>
 279 <pre>
 280     Copyright 1998-2001,2003-2004 Gisle Aas.
 281     Copyright 1995-1996 Neil Winton.</pre>
 282 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 283 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 284 <big><strong><span class="block">&nbsp;Digest - Modules that calculate message digests</span></strong></big>
 285 </td></tr>
 286 </table>
 287
 288 </body>
 289
 290 </html>