iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add first draft of 'API for Cryptographic Hash Functions v2.0'

This commit is contained in:
Christian Heimes 2013-08-17 14:30:44 +02:00
parent a666aa670b
commit 7dce5d07bd
1 changed files with 93 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
pep-0452.txt
View File

@ -1,12 +1,13 @@
PEP: 247
Title: API for Cryptographic Hash Functions
PEP: 452
Title: API for Cryptographic Hash Functions v2.0
Version: $Revision$
Last-Modified: $Date$
Author: A.M. Kuchling <amk@amk.ca>
Status: Final
Author: A.M. Kuchling <amk@amk.ca>, Christian Heimes <christian@python.org>
Status: Draft
Type: Informational
Created: 23-Mar-2001
Post-History: 20-Sep-2001
Created: 15-Aug-2013
Post-History:
Replaces: 247
Abstract
@ -35,11 +36,19 @@ Specification
into the object's starting state, as if obj.update(string) was
called.
After creating a hashing object, arbitrary strings can be fed
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'
@ -59,7 +68,7 @@ Specification
Hashes with a variable output size will set this variable to
None.
Hashing objects require a single attribute:
Hashing objects require the following attribute:
digest_size
@ -71,6 +80,20 @@ Specification
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 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:
@ -81,7 +104,7 @@ Specification
digest()
Return the hash value of this hashing object as a string
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.
@ -95,26 +118,33 @@ Specification
update(string)
Hash 'string' into the current state of the hashing object.
update() can be called any number of times during a hashing
object's lifetime.
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.update('abc')
>>> m.block_size
64
>>> m.update(b'abc')
>>> m.digest()
'\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'
b'\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'
>>> m.hexdigest()
'900150983cd24fb0d6963f7d28e17f72'
>>> MD5.new('abc').digest()
'\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'
>>> MD5.new(b'abc').digest()
b'\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'
Rationale
@ -145,12 +175,58 @@ Rationale
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'.
Recommanded 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