PEP: 247 Title: API for Cryptographic Hash Functions Version: $Revision$ Author: A.M. Kuchling 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=) (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: