Initial checkin of hashing API draft

pep-0247.txt

@@ -0,0 +1,102 @@
+PEP: 247
+Title: API for Cryptographic Hash Functions
+Status: Draft
+Version: $Revision$
+Author: A.M. Kuchling <amk1@bigfoot.com>
+Type: Informational
+Created: 23-Mar-2001
+Post-History:
+
+Abstract
+
+   There are several different modules available that implement 
+   cryptographic hashing algorithms such as MD5 or SHA.  This document 
+   specifies a standard API for such algorithms, to make it easier to 
+   switch between different implementations.
+
+
+Specification
+
+   All hashing modules should present the same interface.  Additional
+   methods or variables can be added, but those described in this
+   document should always be present.  
+
+   Hash function modules define one function:
+
+   new([string], [key])
+   
+      Create a new hashing object and return it.  You can now feed
+      arbitrary strings into the object using its update() method, and
+      can ask for the hash value at any time by calling its digest()
+      method.
+
+      The 'string' parameter, if supplied, will be immediately hashed
+      into the object's starting state.  For keyed hashes such as
+      HMAC, 'key' is a string containing the starting key.
+
+   Hash function modules define one variable:
+
+   digest_size
+
+      An integer value; the size of the digest produced by the hashing
+      objects, measured in bytes. You could also obtain this value by
+      creating a sample object, and taking the length of the digest
+      string it returns, but using digest_size is faster.
+
+   The methods for hashing objects are always the following:
+
+   clear()
+
+      Reset this hashing object to its initial state, as if the object
+      was created from new(key=<initially specified key>) 
+      (XXX what should this do for a keyed hash?  A proposed semantic follows:)
+      There is no way to supply a starting string as there is for the
+      new() function, and there's no way to change the key specified
+      for a keyed hash.
+
+   copy()
+
+      Return a separate copy of this hashing object. An update to this
+      copy won't affect the original object.
+
+   digest()
+
+      Return the hash value of this hashing object, as a string
+      containing 8-bit data. The object is not altered in any way by
+      this function; you can continue updating the object after
+      calling this function.
+
+   update(arg)
+
+      Update this hashing object with the string arg.
+
+   For convenience, hashing objects also have a digest_size attribute,
+   measuring the size of the resulting digest in bytes.  This is
+   identical to the module-level digest_size variable.
+
+   Here's an example, using a module named 'MD5':
+
+       >>> from Crypto.Hash import MD5
+       >>> m = MD5.new()
+       >>> m.update('abc')
+       >>> m.digest()
+       '\220\001P\230<\322O\260\326\226?@}(\341\177r'
+
+   Or, more compactly:
+
+       >>> MD5.new('abc').digest()
+       '\220\001P\230<\322O\260\326\226?@}(\341\177r'
+
+
+Copyright
+
+    This document has been placed in the public domain.
+
+
+
+
+Local Variables:
+mode: indented-text
+indent-tabs-mode: nil
+End:
+