[Python-checkins] cpython (merge 3.5 -> default): Issue #26390: Merge pbkdf2_hmac() doc from 3.5

[martin.panter]

https://hg.python.org/cpython/rev/a74420677e6b
changeset:   100340:a74420677e6b
parent:      100337:a8c761bcbf3f
parent:      100338:7609aaf180b4
user:        Martin Panter <vadmium+py at gmail.com>
date:        Fri Feb 26 00:41:38 2016 +0000
summary:
  Issue #26390: Merge pbkdf2_hmac() doc from 3.5

files:
  Doc/library/hashlib.rst  |  13 +++++++------
  Lib/test/test_hashlib.py |   3 +++
  2 files changed, 10 insertions(+), 6 deletions(-)


diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst
--- a/Doc/library/hashlib.rst
+++ b/Doc/library/hashlib.rst
@@ -185,22 +185,23 @@
 include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
 
 
-.. function:: pbkdf2_hmac(name, password, salt, rounds, dklen=None)
+.. function:: pbkdf2_hmac(hash_name, password, salt, iterations, dklen=None)
 
    The function provides PKCS#5 password-based key derivation function 2. It
    uses HMAC as pseudorandom function.
 
-   The string *name* is the desired name of the hash digest algorithm for
+   The string *hash_name* is the desired name of the hash digest algorithm for
    HMAC, e.g. 'sha1' or 'sha256'. *password* and *salt* are interpreted as
    buffers of bytes. Applications and libraries should limit *password* to
-   a sensible value (e.g. 1024). *salt* should be about 16 or more bytes from
+   a sensible length (e.g. 1024). *salt* should be about 16 or more bytes from
    a proper source, e.g. :func:`os.urandom`.
 
-   The number of *rounds* should be chosen based on the hash algorithm and
-   computing power. As of 2013, at least 100,000 rounds of SHA-256 is suggested.
+   The number of *iterations* should be chosen based on the hash algorithm and
+   computing power. As of 2013, at least 100,000 iterations of SHA-256 are
+   suggested.
 
    *dklen* is the length of the derived key. If *dklen* is ``None`` then the
-   digest size of the hash algorithm *name* is used, e.g. 64 for SHA-512.
+   digest size of the hash algorithm *hash_name* is used, e.g. 64 for SHA-512.
 
    >>> import hashlib, binascii
    >>> dk = hashlib.pbkdf2_hmac('sha256', b'password', b'salt', 100000)
diff --git a/Lib/test/test_hashlib.py b/Lib/test/test_hashlib.py
--- a/Lib/test/test_hashlib.py
+++ b/Lib/test/test_hashlib.py
@@ -513,6 +513,9 @@
         self.assertRaises(ValueError, pbkdf2, 'sha1', b'pass', b'salt', 1, -1)
         with self.assertRaisesRegex(ValueError, 'unsupported hash type'):
             pbkdf2('unknown', b'pass', b'salt', 1)
+        out = pbkdf2(hash_name='sha1', password=b'password', salt=b'salt',
+            iterations=1, dklen=None)
+        self.assertEqual(out, self.pbkdf2_results['sha1'][0][0])
 
     def test_pbkdf2_hmac_py(self):
         self._test_pbkdf2_hmac(py_hashlib.pbkdf2_hmac)

-- 
Repository URL: https://hg.python.org/cpython