[Python-checkins] bpo-42982: update pbkdf2 example & add another link (GH-30966) (#30968)

[ned-deily]

https://github.com/python/cpython/commit/7dbb2f8eaf07c105f4d2bb0fe61763463e68372d
commit: 7dbb2f8eaf07c105f4d2bb0fe61763463e68372d
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: ned-deily <nad at python.org>
date: 2022-03-01T15:56:25-05:00
summary:

bpo-42982: update pbkdf2 example & add another link (GH-30966) (#30968)

Automerge-Triggered-By: GH:gpshead
(cherry picked from commit ace0aa2a2793ba4a2b03e56c4ec375c5470edee8)

Co-authored-by: Gregory P. Smith <greg at krypto.org>

files:
M Doc/library/hashlib.rst

diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst
index 269e8a834d58d..aa24131f8bf44 100644
--- a/Doc/library/hashlib.rst
+++ b/Doc/library/hashlib.rst
@@ -251,15 +251,17 @@ include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
    The number of *iterations* should be chosen based on the hash algorithm and
    computing power. As of 2022, hundreds of thousands of iterations of SHA-256
    are suggested. For rationale as to why and how to choose what is best for
-   your application, read *Appendix A.2.2* of NIST-SP-800-132_.
+   your application, read *Appendix A.2.2* of NIST-SP-800-132_. The answers
+   on the `stackexchange pbkdf2 iterations question`_ explain in detail.
 
    *dklen* is the length of the derived key. If *dklen* is ``None`` then the
    digest size of the hash algorithm *hash_name* is used, e.g. 64 for SHA-512.
 
-   >>> import hashlib
-   >>> dk = hashlib.pbkdf2_hmac('sha256', b'password', b'salt', 100000)
+   >>> from hashlib import pbkdf2_hmac
+   >>> our_app_iters = 500_000  # Application specific, read above.
+   >>> dk = pbkdf2_hmac('sha256', b'password', b'bad salt'*2, our_app_iters)
    >>> dk.hex()
-   '0394a2ede332c9a13eb82e9b24631604c31df978b4e2f0fbd2c549944f9d79a5'
+   '15530bba69924174860db778f2c6f8104d3aaf9d26241840c8c4a641c8d000a9'
 
    .. versionadded:: 3.4
 
@@ -733,7 +735,7 @@ Domain Dedication 1.0 Universal:
 .. _ChaCha: https://cr.yp.to/chacha.html
 .. _pyblake2: https://pythonhosted.org/pyblake2/
 .. _NIST-SP-800-132: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf
-
+.. _stackexchange pbkdf2 iterations question: https://security.stackexchange.com/questions/3959/recommended-of-iterations-when-using-pbkdf2-sha256/
 
 
 .. seealso::