250 lines
9.2 KiB
Plaintext
250 lines
9.2 KiB
Plaintext
PEP: 452
|
||
Title: API for Cryptographic Hash Functions v2.0
|
||
Version: $Revision$
|
||
Last-Modified: $Date$
|
||
Author: A.M. Kuchling <amk@amk.ca>, Christian Heimes <christian@python.org>
|
||
Status: Draft
|
||
Type: Informational
|
||
Created: 15-Aug-2013
|
||
Post-History:
|
||
Replaces: 247
|
||
|
||
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]) (unkeyed hashes)
|
||
new(key, [string], [digestmod]) (keyed hashes)
|
||
|
||
Create a new hashing object and return it. The first form is
|
||
for hashes that are unkeyed, such as MD5 or SHA. For keyed
|
||
hashes such as HMAC, 'key' is a required parameter containing
|
||
a string giving the key to use. In both cases, the optional
|
||
'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 bytes 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.
|
||
|
||
Although the parameter is called 'string', hashing objects operate
|
||
on 8-bit data only. Both 'key' and 'string' must be a bytes-like
|
||
object (bytes, bytearray...). A hashing object may support
|
||
one-dimensional, contiguous buffers as argument, too. Text
|
||
(unicode) is no longer supported in Python 3.x. Python 2.x
|
||
implementations may take ASCII-only unicode as argument, but
|
||
portable code should not rely on the feature.
|
||
|
||
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
|
||
None.
|
||
|
||
Hashing objects require the following 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 None is *not* a legal value for this
|
||
attribute.
|
||
|
||
block_size
|
||
|
||
An integer value or ``NotImplemented``; the internal block size
|
||
of the hash algorithm in bytes. The block size is used by the
|
||
HMAC module to pad the secret key to digest_size or to hash the
|
||
secret key if it is longer than digest_size. If no HMAC
|
||
algorithm is standardized for the hash algorithm, return
|
||
``NotImplemented`` instead.
|
||
|
||
name
|
||
|
||
A text string value; the canonical, lowercase name of the hashing
|
||
algorithm. The name should be a suitable parameter for
|
||
:func:`hashlib.new`.
|
||
|
||
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 bytes
|
||
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 bytes-like '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':
|
||
|
||
>>> import hashlib
|
||
>>> from Crypto.Hash import MD5
|
||
>>> m = MD5.new()
|
||
>>> isinstance(m, hashlib.CryptoHash)
|
||
True
|
||
>>> m.name
|
||
'md5'
|
||
>>> m.digest_size
|
||
16
|
||
>>> m.block_size
|
||
64
|
||
>>> m.update(b'abc')
|
||
>>> m.digest()
|
||
b'\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'
|
||
>>> m.hexdigest()
|
||
'900150983cd24fb0d6963f7d28e17f72'
|
||
>>> MD5.new(b'abc').digest()
|
||
b'\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'
|
||
|
||
|
||
Rationale
|
||
|
||
The digest size is measured in bytes, not bits, even though hash
|
||
algorithm sizes are usually quoted in bits; MD5 is a 128-bit
|
||
algorithm and not a 16-byte one, for example. This is because, in
|
||
the sample code I looked at, the length in bytes is often needed
|
||
(to seek ahead or behind in a file; to compute the length of an
|
||
output string) while the length in bits is rarely used.
|
||
Therefore, the burden will fall on the few people actually needing
|
||
the size in bits, who will have to multiply digest_size by 8.
|
||
|
||
It's been suggested that the update() method would be better named
|
||
append(). However, that method is really causing the current
|
||
state of the hashing object to be updated, and update() is already
|
||
used by the md5 and sha modules included with Python, so it seems
|
||
simplest to leave the name update() alone.
|
||
|
||
The order of the constructor's arguments for keyed hashes was a
|
||
sticky issue. It wasn't clear whether the key should come first
|
||
or second. It's a required parameter, and the usual convention is
|
||
to place required parameters first, but that also means that the
|
||
'string' parameter moves from the first position to the second.
|
||
It would be possible to get confused and pass a single argument to
|
||
a keyed hash, thinking that you're passing an initial string to an
|
||
unkeyed hash, but it doesn't seem worth making the interface
|
||
for keyed hashes more obscure to avoid this potential error.
|
||
|
||
|
||
Changes from Version 1.0 to Version 2.0
|
||
|
||
Version 2.0 of API for Cryptographic Hash Functions clarifies some
|
||
aspects of the API and brings it up-to-date. It also formalized aspects
|
||
that were already de-facto standards and provided by most
|
||
implementations.
|
||
|
||
Version 2.0 introduces the following new attributes:
|
||
|
||
name
|
||
|
||
The name property was made mandatory by :issue:`18532`.
|
||
|
||
block_size
|
||
|
||
The new version also specifies that the return value
|
||
``NotImplemented`` prevents HMAC support.
|
||
|
||
Version 2.0 takes the separation of binary and text data in Python
|
||
3.0 into account. The 'string' argument to new() and update() as
|
||
well as the 'key' argument must be bytes-like objects. On Python
|
||
2.x a hashing object may also support ASCII-only unicode. The actual
|
||
name of argument is not changed as it is part of the public API.
|
||
Code may depend on the fact that the argument is called 'string'.
|
||
|
||
|
||
Recommended names for common hashing algorithms
|
||
|
||
algorithm variant recommended name
|
||
---------- --------- ----------------
|
||
MD5 md5
|
||
RIPEMD-160 ripemd160
|
||
SHA-1 sha1
|
||
SHA-2 SHA-224 sha224
|
||
SHA-256 sha256
|
||
SHA-384 sha384
|
||
SHA-512 sha512
|
||
SHA-3 SHA-3-224 sha3_224
|
||
SHA-3-256 sha3_256
|
||
SHA-3-384 sha3_384
|
||
SHA-3-512 sha3_512
|
||
WHIRLPOOL whirlpool
|
||
|
||
|
||
Changes
|
||
|
||
2001-09-17: Renamed clear() to reset(); added digest_size attribute
|
||
to objects; added .hexdigest() method.
|
||
2001-09-20: Removed reset() method completely.
|
||
2001-09-28: Set digest_size to None for variable-size hashes.
|
||
2013-08-15: Added block_size and name attributes; clarified that
|
||
'string' actually referes to bytes-like objects.
|
||
|
||
|
||
Acknowledgements
|
||
|
||
Thanks to Aahz, 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:
|
||
|