diff --git a/pep-0452.txt b/pep-0452.txt index cc05d28f4..a0cef8eeb 100644 --- a/pep-0452.txt +++ b/pep-0452.txt @@ -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 -Status: Final +Author: A.M. Kuchling , Christian Heimes +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. + 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