[PYTHON-CRYPTO] Draft hashing PEP

[Andrew Kuchling]

Here's an informational PEP describing the API for hashing that I
posted to the list last month.  This draft includes the suggested
revisions of dropping the hexdigest() method and adding clear(),
adding an optional key argument to the constructor for a hash object.

Comments requested; if there are none, then its status can be changed
to 'Accepted'.  (No PEP number allocated yet, but I've sent it off to
Barry to get one.)

--amk

PEP: XXX
Title: Standard API for Cryptographic Hash Algorithms
Status: Draft
Version: $Revision: 1.14 $
Author: A.M. Kuchling <amk1 at 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. 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.

   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: