home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _a56a78924df27eee9142b1435a2c4155 < prev    next >
Text File  |  2000-03-23  |  9KB  |  202 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>SHA - Perl interface to the NIST Secure Hash Algorithm</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> SHA - Perl interface to the NIST Secure Hash Algorithm</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="#example and validation">EXAMPLE AND VALIDATION</A></LI>
  26.     <LI><A HREF="#further examples and validation">FURTHER EXAMPLES AND VALIDATION</A></LI>
  27.     <LI><A HREF="#note">NOTE</A></LI>
  28.     <LI><A HREF="#author">AUTHOR</A></LI>
  29. </UL>
  30. <!-- INDEX END -->
  31.  
  32. <HR>
  33. <P>
  34. <H1><A NAME="name">NAME</A></H1>
  35. <P>SHA - Perl interface to the NIST Secure Hash Algorithm</P>
  36. <P>
  37. <HR>
  38. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  39. <UL>
  40. <LI>Linux</LI>
  41. <LI>Solaris</LI>
  42. <LI>Windows</LI>
  43. </UL>
  44. <HR>
  45. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  46. <PRE>
  47.     use SHA;</PRE>
  48. <PRE>
  49.     $version = &SHA::sha_version;</PRE>
  50. <PRE>
  51.     $context = new SHA;
  52.     $context->reset();</PRE>
  53. <PRE>
  54.     $context->add(LIST);
  55.     $context->addfile(HANDLE);</PRE>
  56. <PRE>
  57.     $digest = $context->digest();
  58.     $string = $context->hexdigest();</PRE>
  59. <PRE>
  60.     $digest = $context->hash($string);
  61.     $string = $context->hexhash($string);</PRE>
  62. <P>
  63. <HR>
  64. <H1><A NAME="description">DESCRIPTION</A></H1>
  65. <P>The <STRONG>SHA</STRONG> module allows you to use the NIST SHA message digest algorithm
  66. from within Perl programs.</P>
  67. <P>The sha_version routine returns the version of the algorithm which is being
  68. used: either ``SHA'' for the original algorithm or ``SHA-1'' for the updated
  69. algorithm.</P>
  70. <P>A new SHA context object is created with the <STRONG>new</STRONG> operation.
  71. Multiple simultaneous digest contexts can be maintained, if desired.
  72. The context is updated with the <STRONG>add</STRONG> operation which adds the
  73. strings contained in the <EM>LIST</EM> parameter. Adding two strings
  74. separately is equivalent to adding their concatenation:
  75. <CODE>add('foo', 'bar')</CODE> produces the same effect as <CODE>add('foo')</CODE>,
  76. <CODE>add('bar')</CODE>, which in turn produces the same effect as <CODE>add('foobar')</CODE>.</P>
  77. <P>The final message digest value is returned by the <STRONG>digest</STRONG> operation
  78. as a 20-byte binary string. This operation delivers the result of
  79. operations since the last <STRONG>new</STRONG> or <STRONG>reset</STRONG> operation. Once the
  80. operation has been performed, the context must be <STRONG>reset</STRONG> before
  81. being used to calculate another digest value.</P>
  82. <P>Several convenience functions are also provided. The <STRONG>addfile</STRONG>
  83. operation takes an open file-handle and reads it until end-of file in
  84. 8192-byte blocks adding the contents to the context. The <STRONG>hexdigest</STRONG>
  85. operation calls <STRONG>digest</STRONG> and returns the result as a printable string
  86. of hexadecimal digits in eight-digit groups. The <STRONG>hash</STRONG> operation
  87. performs the complete series of steps: <STRONG>reset</STRONG>, <STRONG>add</STRONG>, <STRONG>digest</STRONG> on
  88. the supplied scalar value, and returns the result as a 20-byte binary
  89. string. The <STRONG>hexhash</STRONG> operation does the same thing, but returns the
  90. result in the format of the <STRONG>hexdigest</STRONG> operation.</P>
  91. <P>
  92. <HR>
  93. <H1><A NAME="example and validation">EXAMPLE AND VALIDATION</A></H1>
  94. <PRE>
  95.     use SHA 1.2;</PRE>
  96. <PRE>
  97.     $ver = &SHA::sha_version;
  98.     $sha = new SHA;</PRE>
  99. <PRE>
  100.     if ($ver eq 'SHA') {
  101.         print "EXPECT:   0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880\n";
  102.     } elsif ($ver eq 'SHA-1') {
  103.         print "EXPECT:   a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d\n";
  104.     } else {
  105.         die "panic! unrecognized output '$ver' from sha_version\n";
  106.     }</PRE>
  107. <PRE>
  108.     $sha->reset();
  109.     $sha->add("abc");
  110.     print "RESULT 1: " . $sha->hexdigest() . "\n";</PRE>
  111. <PRE>
  112.     $sha->reset();
  113.     $sha->add("a", "bc");
  114.     print "RESULT 2: " . $sha->hexdigest() . "\n";</PRE>
  115. <PRE>
  116.     $sha->reset();
  117.     $sha->add("ab", "c");
  118.     print "RESULT 3: " . $sha->hexdigest() . "\n";</PRE>
  119. <PRE>
  120.     $sha->reset();
  121.     $sha->add("a", "b", "c");
  122.     print "RESULT 4: " . $sha->hexdigest() . "\n";</PRE>
  123. <PRE>
  124.     $sha->reset();
  125.     $sha->add("ab");
  126.     $sha->add("c");
  127.     print "RESULT 5: " . $sha->hexdigest() . "\n";</PRE>
  128. <PRE>
  129.     $sha->reset();
  130.     $sha->add("a");
  131.     $sha->add("bc");
  132.     print "RESULT 6: " . $sha->hexdigest() . "\n";</PRE>
  133. <PRE>
  134.     $sha->reset();
  135.     $sha->add("a");
  136.     $sha->add("b");
  137.     $sha->add("c");
  138.     print "RESULT 7: " . $sha->hexdigest() . "\n";</PRE>
  139. <PRE>
  140.     print "RESULT 8: " . $sha->hexhash("abc") . "\n";</PRE>
  141. <PRE>
  142.     $sha->reset();
  143.     $sha->add("ab", "c");
  144.     print "result a: " . unpack("H*", ($sha->digest())) . "\n";</PRE>
  145. <PRE>
  146.     print "result b: " . unpack("H*", ($sha->hash("abc"))) . "\n";</PRE>
  147. <P>The above example will produce one of two outputs. If the original SHA
  148. algorithm is being used, the output will be:</P>
  149. <PRE>
  150.     EXPECT:   0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
  151.     RESULT 1: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
  152.     RESULT 2: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
  153.     RESULT 3: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
  154.     RESULT 4: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
  155.     RESULT 5: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
  156.     RESULT 6: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
  157.     RESULT 7: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
  158.     RESULT 8: 0164b8a9 14cd2a5e 74c4f7ff 082c4d97 f1edf880
  159.     result a: 0164b8a914cd2a5e74c4f7ff082c4d97f1edf880
  160.     result b: 0164b8a914cd2a5e74c4f7ff082c4d97f1edf880</PRE>
  161. <P>If the new SHA-1 algorithm is being used, the output will be</P>
  162. <PRE>
  163.     EXPECT:   a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
  164.     RESULT 1: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
  165.     RESULT 2: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
  166.     RESULT 3: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
  167.     RESULT 4: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
  168.     RESULT 5: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
  169.     RESULT 6: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
  170.     RESULT 7: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
  171.     RESULT 8: a9993e36 4706816a ba3e2571 7850c26c 9cd0d89d
  172.     result a: a9993e364706816aba3e25717850c26c9cd0d89d
  173.     result b: a9993e364706816aba3e25717850c26c9cd0d89d</PRE>
  174. <P>provided that the implementation is working correctly.</P>
  175. <P>
  176. <HR>
  177. <H1><A NAME="further examples and validation">FURTHER EXAMPLES AND VALIDATION</A></H1>
  178. <P>The file sha_driver.pl contains further validation data and examples of
  179. how to use the SHA module. It may be invoked with the <STRONG>-h</STRONG> flag, which gives
  180. further usage instructions; the <STRONG>-x</STRONG> flag runs a few more tests.</P>
  181. <P>
  182. <HR>
  183. <H1><A NAME="note">NOTE</A></H1>
  184. <P>The SHA extension may be redistributed under the same terms as Perl.
  185. The SHA code is in the public domain. It was heavily modified by
  186. Uwe Hollerbach following the implementation by Peter Gutmann.</P>
  187. <P>
  188. <HR>
  189. <H1><A NAME="author">AUTHOR</A></H1>
  190. <P>The SHA interface was written by Uwe Hollerbach <CODE>uh@alumni.caltech.edu</CODE>,
  191. shamelessly stealing from the MD5 interface written by Neil Winton
  192. (<CODE>N.Winton@axion.bt.co.uk</CODE>).</P>
  193. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  194. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  195. <STRONG><P CLASS=block> SHA - Perl interface to the NIST Secure Hash Algorithm</P></STRONG>
  196. </TD></TR>
  197. </TABLE>
  198.  
  199. </BODY>
  200.  
  201. </HTML>
  202.