home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _fd72bf1ea6f19efb6a59fbefcf0eb255 < prev    next >
Text File  |  2000-03-23  |  7KB  |  172 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Digest:: - Modules that calculate message digests</TITLE>
  5. <LINK REL="stylesheet" HREF="../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Digest:: - Modules that calculate message digests</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  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="#see also">SEE ALSO</A></LI>
  27.     <LI><A HREF="#author">AUTHOR</A></LI>
  28. </UL>
  29. <!-- INDEX END -->
  30.  
  31. <HR>
  32. <P>
  33. <H1><A NAME="name">NAME</A></H1>
  34. <P>Digest:: - Modules that calculate message digests</P>
  35. <P>
  36. <HR>
  37. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  38. <UL>
  39. <LI>Linux</LI>
  40. <LI>Solaris</LI>
  41. <LI>Windows</LI>
  42. </UL>
  43. <HR>
  44. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  45. <PRE>
  46.   $md2 = Digest->MD2;
  47.   $md5 = Digest->MD5;</PRE>
  48. <PRE>
  49.   $sha1 = Digest->SHA1;
  50.   $sha1 = Digest->new("SHA-1");</PRE>
  51. <PRE>
  52.   $hmac = Digest->HMAC_MD5($key);</PRE>
  53. <P>
  54. <HR>
  55. <H1><A NAME="description">DESCRIPTION</A></H1>
  56. <P>The <CODE>Digest::</CODE> modules calculate digests, also called ``fingerprints''
  57. or ``hashes'', of some data, called a message.  The digest is some small
  58. fixed size string.  The actual size of the digest depend of the
  59. algorithm used.  The message is simply a sequence of arbitrary bytes.</P>
  60. <P>An important property of the digest algorithms is that the digest is
  61. <EM>likely</EM> 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 <EM>hard</EM> 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.</P>
  66. <P>All <CODE>Digest::</CODE> modules provide the same programming interface.  A
  67. functional interface for simple use, as well as an object oriented
  68. interface that can handle messages of arbitrary length and which can
  69. read files directly.</P>
  70. <P>The digest can be delivered in three formats:</P>
  71. <DL>
  72. <DT><STRONG><A NAME="item_binary"><EM>binary</EM></A></STRONG><BR>
  73. <DD>
  74. This is the most compact form, but it is not well suited for printing
  75. or embedding in places that can't handle arbitrary data.
  76. <P></P>
  77. <DT><STRONG><A NAME="item_hex"><EM>hex</EM></A></STRONG><BR>
  78. <DD>
  79. A twice as long string of (lowercase) hexadecimal digits.
  80. <P></P>
  81. <DT><STRONG><A NAME="item_base64"><EM>base64</EM></A></STRONG><BR>
  82. <DD>
  83. A string of portable printable characters.  This is the base64 encoded
  84. representation of the digest with any trailing padding removed.  The
  85. string will be about 30% longer than the binary version.
  86. <A HREF="../../site/lib/MIME/Base64.html">the MIME::Base64 manpage</A> tells you more about this encoding.
  87. <P></P></DL>
  88. <P>The functional interface is simply importable functions with the same
  89. name as the algorithm.  The functions take the message as argument and
  90. return the digest.  Example:</P>
  91. <PRE>
  92.   use Digest::MD5 qw(md5);
  93.   $digest = md5($message);</PRE>
  94. <P>There are also versions of the functions with ``_hex'' or ``_base64''
  95. appended to the name, which returns the digest in the indicated form.</P>
  96. <P>
  97. <HR>
  98. <H1><A NAME="oo interface">OO INTERFACE</A></H1>
  99. <P>The following methods are available for all <CODE>Digest::</CODE> modules:</P>
  100. <DL>
  101. <DT><STRONG><A NAME="item_XXX">$ctx = Digest-><CODE>XXX($arg,...)</CODE></A></STRONG><BR>
  102. <DD>
  103. <DT><STRONG><A NAME="item_new">$ctx = Digest->new(XXX => $arg,...)</A></STRONG><BR>
  104. <DD>
  105. <DT><STRONG>$ctx = Digest::XXX-><CODE>new($arg,...)</CODE></STRONG><BR>
  106. <DD>
  107. The constructor returns some object that encapsulate the state of the
  108. message-digest algorithm.  You can add data to the object and finally
  109. ask for the digest.  The ``XXX'' should of course be replaced by the proper
  110. name of the digest algorithm you want to use.
  111. <P>The two first forms are simply syntactic sugar which automatically
  112. load the right module on first use.  The second form allow you to use
  113. algorithm names which contains letters which are not legal perl
  114. identifiers, e.g. ``SHA-1''.</P>
  115. <P>If <A HREF="#item_new"><CODE>new()</CODE></A> is called as a instance method (i.e. $ctx->new) it will just
  116. reset the state the object to the state of a newly created object.  No
  117. new object is created in this case, and the return value is the
  118. reference to the object (i.e. $ctx).</P>
  119. <P></P>
  120. <DT><STRONG><A NAME="item_reset">$ctx->reset</A></STRONG><BR>
  121. <DD>
  122. This is just an alias for $ctx->new.
  123. <P></P>
  124. <DT><STRONG><A NAME="item_add">$ctx-><CODE>add($data,...)</CODE></A></STRONG><BR>
  125. <DD>
  126. The $data provided as argument are appended to the message we
  127. calculate the digest for.  The return value is the $ctx object itself.
  128. <P></P>
  129. <DT><STRONG><A NAME="item_addfile">$ctx-><CODE>addfile($io_handle)</CODE></A></STRONG><BR>
  130. <DD>
  131. The $io_handle is read until EOF and the content is appended to the
  132. message we calculate the digest for.  The return value is the $ctx
  133. object itself.
  134. <P></P>
  135. <DT><STRONG><A NAME="item_digest">$ctx->digest</A></STRONG><BR>
  136. <DD>
  137. Return the binary digest for the message.
  138. <P>Note that the <A HREF="#item_digest"><CODE>digest</CODE></A> operation is effectively a destructive,
  139. read-once operation. Once it has been performed, the $ctx object is
  140. automatically <A HREF="#item_reset"><CODE>reset</CODE></A> and can be used to calculate another digest
  141. value.</P>
  142. <P></P>
  143. <DT><STRONG><A NAME="item_hexdigest">$ctx->hexdigest</A></STRONG><BR>
  144. <DD>
  145. Same as $ctx->digest, but will return the digest in hexadecimal form.
  146. <P></P>
  147. <DT><STRONG><A NAME="item_b64digest">$ctx->b64digest</A></STRONG><BR>
  148. <DD>
  149. Same as $ctx->digest, but will return the digest as a base64 encoded
  150. string.
  151. <P></P></DL>
  152. <P>
  153. <HR>
  154. <H1><A NAME="see also">SEE ALSO</A></H1>
  155. <P><A HREF="../../site/lib/Digest/MD5.html">the Digest::MD5 manpage</A>, <A HREF="../../site/lib/Digest/SHA1.html">the Digest::SHA1 manpage</A>, <A HREF="../../site/lib/Digest/HMAC.html">the Digest::HMAC manpage</A>, <A HREF="../../site/lib/Digest/MD2.html">the Digest::MD2 manpage</A></P>
  156. <P><A HREF="../../site/lib/MIME/Base64.html">the MIME::Base64 manpage</A></P>
  157. <P>
  158. <HR>
  159. <H1><A NAME="author">AUTHOR</A></H1>
  160. <P>Gisle Aas <<A HREF="mailto:gisle@aas.no">gisle@aas.no</A>></P>
  161. <P>The <CODE>Digest::</CODE> interface is based on the interface originally
  162. developed by Neil Winton for his <CODE>MD5</CODE> module.</P>
  163. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  164. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  165. <STRONG><P CLASS=block> Digest:: - Modules that calculate message digests</P></STRONG>
  166. </TD></TR>
  167. </TABLE>
  168.  
  169. </BODY>
  170.  
  171. </HTML>
  172.