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

pep-0452.txt

@@ -1,12 +1,13 @@
-PEP: 247
+PEP: 452
-Title: API for Cryptographic Hash Functions
+Title: API for Cryptographic Hash Functions v2.0
 Version: $Revision$
 Last-Modified: $Date$
-Author: A.M. Kuchling <amk@amk.ca>
+Author: A.M. Kuchling <amk@amk.ca>, Christian Heimes <christian@python.org>
-Status: Final
+Status: Draft
 Type: Informational
-Created: 23-Mar-2001
+Created: 15-Aug-2013
-Post-History: 20-Sep-2001
+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.
+        Hash bytes-like 'string' into the current state of the hashing
-        update() can be called any number of times during a hashing
+        object. update() can be called any number of times during a
-        object's lifetime.
+        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()
+        >>> MD5.new(b'abc').digest()
-        '\x90\x01P\x98<\xd2O\xb0\xd6\x96?}(\xe1\x7fr'
+        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