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:

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: