103 lines
3.0 KiB
Plaintext
103 lines
3.0 KiB
Plaintext
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:
|
||
|