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

reSTify PEP 452 (#327)

This commit is contained in:
Huang Huang 2017-08-17 06:53:46 +08:00 committed by Brett Cannon
parent 7f8e97ca3f
commit a5e937ea43
1 changed files with 192 additions and 179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

227
pep-0452.txt
View File

@ -5,40 +5,43 @@ Last-Modified: $Date$
Author: A.M. Kuchling <amk@amk.ca>, Christian Heimes <christian@python.org> Author: A.M. Kuchling <amk@amk.ca>, Christian Heimes <christian@python.org>
Status: Draft Status: Draft
Type: Informational Type: Informational
Content-Type: text/x-rst
Created: 15-Aug-2013 Created: 15-Aug-2013
Post-History: Post-History:
Replaces: 247 Replaces: 247
Abstract Abstract
========
There are several different modules available that implement There are several different modules available that implement
cryptographic hashing algorithms such as MD5 or SHA. This cryptographic hashing algorithms such as MD5 or SHA. This
document specifies a standard API for such algorithms, to make it document specifies a standard API for such algorithms, to make it
easier to switch between different implementations. easier to switch between different implementations.
Specification Specification
=============
All hashing modules should present the same interface. Additional All hashing modules should present the same interface. Additional
methods or variables can be added, but those described in this methods or variables can be added, but those described in this
document should always be present. document should always be present.
Hash function modules define one function: Hash function modules define one function:
new([string]) (unkeyed hashes) ``new([string]) (unkeyed hashes)``
new(key, [string], [digestmod]) (keyed hashes)
``new(key, [string], [digestmod]) (keyed hashes)``
Create a new hashing object and return it. The first form is Create a new hashing object and return it. The first form is
for hashes that are unkeyed, such as MD5 or SHA. For keyed for hashes that are unkeyed, such as MD5 or SHA. For keyed
hashes such as HMAC, 'key' is a required parameter containing hashes such as HMAC, 'key' is a required parameter containing
a string giving the key to use. In both cases, the optional a string giving the key to use. In both cases, the optional
'string' parameter, if supplied, will be immediately hashed 'string' parameter, if supplied, will be immediately hashed
into the object's starting state, as if obj.update(string) was into the object's starting state, as if ``obj.update(string)`` was
called. called.
After creating a hashing object, arbitrary bytes can be fed After creating a hashing object, arbitrary bytes can be fed
into the object using its update() method, and the hash value into the object using its ``update()`` method, and the hash value
can be obtained at any time by calling the object's digest() can be obtained at any time by calling the object's ``digest()``
method. method.
Although the parameter is called 'string', hashing objects operate Although the parameter is called 'string', hashing objects operate
@ -56,10 +59,9 @@ Specification
variable number of rounds and several different output sizes, variable number of rounds and several different output sizes,
and they should default to values believed to be secure. and they should default to values believed to be secure.
Hash function modules define one variable: Hash function modules define one variable:
digest_size
``digest_size``
An integer value; the size of the digest produced by the An integer value; the size of the digest produced by the
hashing objects created by this module, measured in bytes. hashing objects created by this module, measured in bytes.
You could also obtain this value by creating a sample object You could also obtain this value by creating a sample object
@ -68,64 +70,57 @@ Specification
Hashes with a variable output size will set this variable to Hashes with a variable output size will set this variable to
None. None.
Hashing objects require the following attribute: Hashing objects require the following attribute:
digest_size
``digest_size``
This attribute is identical to the module-level digest_size This attribute is identical to the module-level digest_size
variable, measuring the size of the digest produced by the variable, measuring the size of the digest produced by the
hashing object, measured in bytes. If the hash has a variable hashing object, measured in bytes. If the hash has a variable
output size, this output size must be chosen when the hashing output size, this output size must be chosen when the hashing
object is created, and this attribute must contain the object is created, and this attribute must contain the
selected size. Therefore, None is *not* a legal value for this selected size. Therefore, ``None`` is **not** a legal value for this
attribute. attribute.
block_size ``block_size``
An integer value or ``NotImplemented``; the internal block size An integer value or ``NotImplemented``; the internal block size
of the hash algorithm in bytes. The block size is used by the 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 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 secret key if it is longer than ``digest_size``. If no HMAC
algorithm is standardized for the hash algorithm, return algorithm is standardized for the hash algorithm, return
``NotImplemented`` instead. ``NotImplemented`` instead.
name ``name``
A text string value; the canonical, lowercase name of the hashing A text string value; the canonical, lowercase name of the hashing
algorithm. The name should be a suitable parameter for algorithm. The name should be a suitable parameter for
:func:`hashlib.new`. ``hashlib.new``.
Hashing objects require the following methods: Hashing objects require the following methods:
copy()
``copy()``
Return a separate copy of this hashing object. An update to Return a separate copy of this hashing object. An update to
this copy won't affect the original object. this copy won't affect the original object.
digest() ``digest()``
Return the hash value of this hashing object as a bytes Return the hash value of this hashing object as a bytes
containing 8-bit data. The object is not altered in any way containing 8-bit data. The object is not altered in any way
by this function; you can continue updating the object after by this function; you can continue updating the object after
calling this function. calling this function.
hexdigest() ``hexdigest()``
Return the hash value of this hashing object as a string Return the hash value of this hashing object as a string
containing hexadecimal digits. Lowercase letters should be used containing hexadecimal digits. Lowercase letters should be used
for the digits 'a' through 'f'. Like the .digest() method, this for the digits 'a' through 'f'. Like the ``.digest()`` method, this
method mustn't alter the object. method mustn't alter the object.
update(string) ``update(string)``
Hash bytes-like 'string' into the current state of the hashing Hash bytes-like 'string' into the current state of the hashing
object. update() can be called any number of times during a object. ``update()`` can be called any number of times during a
hashing object's lifetime. hashing object's lifetime.
Hashing modules can define additional module-level functions or Hashing modules can define additional module-level functions or
object methods and still be compliant with this specification. object methods and still be compliant with this specification.
Here's an example, using a module named 'MD5': Here's an example, using a module named 'MD5'::
>>> import hashlib >>> import hashlib
>>> from Crypto.Hash import MD5 >>> from Crypto.Hash import MD5
@ -148,102 +143,120 @@ Specification
Rationale Rationale
=========
The digest size is measured in bytes, not bits, even though hash 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 sizes are usually quoted in bits; MD5 is a 128-bit
algorithm and not a 16-byte one, for example. This is because, in 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 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 (to seek ahead or behind in a file; to compute the length of an
output string) while the length in bits is rarely used. output string) while the length in bits is rarely used.
Therefore, the burden will fall on the few people actually needing Therefore, the burden will fall on the few people actually needing
the size in bits, who will have to multiply digest_size by 8. 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 It's been suggested that the ``update()`` method would be better named
append(). However, that method is really causing the current ``append()``. However, that method is really causing the current
state of the hashing object to be updated, and update() is already 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 used by the md5 and sha modules included with Python, so it seems
simplest to leave the name update() alone. simplest to leave the name ``update()`` alone.
The order of the constructor's arguments for keyed hashes was a The order of the constructor's arguments for keyed hashes was a
sticky issue. It wasn't clear whether the key should come first sticky issue. It wasn't clear whether the key should come first
or second. It's a required parameter, and the usual convention is or second. It's a required parameter, and the usual convention is
to place required parameters first, but that also means that the to place required parameters first, but that also means that the
'string' parameter moves from the first position to the second. 'string' parameter moves from the first position to the second.
It would be possible to get confused and pass a single argument to 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 a keyed hash, thinking that you're passing an initial string to an
unkeyed hash, but it doesn't seem worth making the interface unkeyed hash, but it doesn't seem worth making the interface
for keyed hashes more obscure to avoid this potential error. for keyed hashes more obscure to avoid this potential error.
Changes from Version 1.0 to Version 2.0 Changes from Version 1.0 to Version 2.0
=======================================
Version 2.0 of API for Cryptographic Hash Functions clarifies some 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 aspects of the API and brings it up-to-date. It also formalized aspects
that were already de facto standards and provided by most that were already de facto standards and provided by most
implementations. implementations.
Version 2.0 introduces the following new attributes: Version 2.0 introduces the following new attributes:
name ``name``
The name property was made mandatory by `issue 18532`_.
The name property was made mandatory by :issue:`18532`.
block_size
``block_size``
The new version also specifies that the return value The new version also specifies that the return value
``NotImplemented`` prevents HMAC support. ``NotImplemented`` prevents HMAC support.
Version 2.0 takes the separation of binary and text data in Python 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 3.0 into account. The 'string' argument to ``new()`` and ``update()`` as
well as the 'key' argument must be bytes-like objects. On Python 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 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. 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'. Code may depend on the fact that the argument is called 'string'.
Recommended names for common hashing algorithms Recommended names for common hashing algorithms
===============================================
algorithm variant recommended name +------------+------------+-------------------+
---------- --------- ---------------- | algorithm | variant | recommended name |
MD5 md5 +============+============+===================+
RIPEMD-160 ripemd160 | MD5 | | md5 |
SHA-1 sha1 +------------+------------+-------------------+
SHA-2 SHA-224 sha224 | RIPEMD-160 | | ripemd160 |
SHA-256 sha256 +------------+------------+-------------------+
SHA-384 sha384 | SHA-1 | | sha1 |
SHA-512 sha512 +------------+------------+-------------------+
SHA-3 SHA-3-224 sha3_224 | SHA-2 | SHA-224 | sha224 |
SHA-3-256 sha3_256 + +------------+-------------------+
SHA-3-384 sha3_384 | | SHA-256 | sha256 |
SHA-3-512 sha3_512 + +------------+-------------------+
WHIRLPOOL whirlpool | | 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 Changes
=======
2001-09-17: Renamed clear() to reset(); added digest_size attribute * 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-20: Removed ``reset()`` method completely.
2001-09-28: Set digest_size to None for variable-size hashes. * 2001-09-28: Set ``digest_size`` to ``None`` for variable-size hashes.
2013-08-15: Added block_size and name attributes; clarified that * 2013-08-15: Added ``block_size`` and ``name`` attributes; clarified that
'string' actually referes to bytes-like objects. 'string' actually referes to bytes-like objects.
Acknowledgements Acknowledgements
================
Thanks to Aahz, Andrew Archibald, Rich Salz, Itamar Thanks to Aahz, Andrew Archibald, Rich Salz, Itamar
Shtull-Trauring, and the readers of the python-crypto list for Shtull-Trauring, and the readers of the python-crypto list for
their comments on this PEP. their comments on this PEP.
Copyright Copyright
=========
This document has been placed in the public domain. This document has been placed in the public domain.
.. _issue 18532: http://bugs.python.org/issue18532
Local Variables:
mode: indented-text
indent-tabs-mode: nil
End:
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
End: