diff --git a/pep-0247.txt b/pep-0247.txt new file mode 100644 index 000000000..203a6623a --- /dev/null +++ b/pep-0247.txt @@ -0,0 +1,102 @@ +PEP: 247 +Title: API for Cryptographic Hash Functions +Status: Draft +Version: $Revision$ +Author: A.M. Kuchling +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: +