python-peps/pep-0247.txt

PEP: 247
Title: API for Cryptographic Hash Functions
Version: $Revision$
Author: A.M. Kuchling <akuchlin@mems-exchange.org>
Status: Draft
Type: Informational
Created: 23-Mar-2001
Post-History: 20-Sep-2001

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])
    new([key] , [string])

        Create a new hashing object and return it.  The first form is
        for hashes that are unkeyed; most hashes such as MD5 or SHA
        are unkeyed.  For keyed hashes such as HMAC, 'key' is a string
        containing the starting key.  The 'string' parameter, if
        supplied, will be immediately hashed into the object's
        starting state, as if obj.update(string) was called.
        
        After creating a hashing object, arbitrary strings can be fed
        into the object using its update() method, and the hash value
        can be obtained at any time by calling the object's digest()
        method.

        Arbitrary additional keyword arguments can be added to this
        function, but if they're not supplied, sensible default values
        should be used.  For example, 'rounds' and 'digest_size'
        keywords could be added for a hash function which supports a
        variable number of rounds and several different output sizes,
        and they should default to values believed to be secure.

    Hash function modules define one variable:

    digest_size

        An integer value; the size of the digest produced by the
        hashing objects created by this module, measured in bytes.
        You could also obtain this value by creating a sample object
        and accessing its 'digest_size' attribute, but it can be
        convenient to have this value available from the module.
        Hashes with a variable output size will set this variable to 0.

    Hashing objects require a single attribute:

    digest_size

        This attribute is identical to the module-level digest_size
        variable, measuring the size of the digest produced by the
        hashing object, measured in bytes.  If the hash has a variable
        output size, this output size must be chosen when the hashing
        object is created, and this attribute must contain the
        selected size.  Therefore 0 is *not* a legal value for this
        attribute.
                

    Hashing objects require the following methods:

    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.

    hexdigest()

        Return the hash value of this hashing object as a string
        containing hexadecimal digits.  Lowercase letters should be used 
        for the digits 'a' through 'f'.  Like the .digest() method, this
        method mustn't alter the object.
        
    update(string)

        Hash 'string' into the current state of the hashing object.
        update() can be called any number of times during a hashing
        object's lifetime.

    Hashing modules can define additional module-level functions or 
    object methods and still be compliant with this specification.
    
    Here's an example, using a module named 'MD5':

        >>> from Crypto.Hash import MD5
        >>> m = MD5.new()
        >>> m.digest_size
        16
        >>> m.update('abc')
        >>> m.digest()
        '\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'    
        >>> m.hexdigest()
        '900150983cd24fb0d6963f7d28e17f72' 
        >>> MD5.new('abc').digest()
        '\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'    


Changes

    2001-09-17: Renamed clear() to reset(); added digest_size attribute
    to objects; added .hexdigest() method.
    2001-09-20: Removed reset() method completely.


Acknowledgements

    Thanks to Andrew Archibald, Rich Salz, Itamar Shtull-Trauring, and
    the readers of the python-crypto list for their comments on this
    PEP.


Copyright

    This document has been placed in the public domain.



Local Variables:
mode: indented-text
indent-tabs-mode: nil
End: