From acee4726668272e893ca8df94756c3bb1fab2492 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Thu, 27 Jan 2022 19:27:57 +0000 Subject: [PATCH 1/4] bpo-42982: update the pbkdf2 example code. along with a comment telling people to read the docs instead of blindly copy and pasting a value. --- Doc/library/hashlib.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst index 269e8a834d58d4..3d8efa099020de 100644 --- a/Doc/library/hashlib.rst +++ b/Doc/library/hashlib.rst @@ -256,10 +256,11 @@ include a `salt `_. *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 From 55e7145cfe8ed3554e0b820fc66afef71465453a Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Thu, 27 Jan 2022 19:32:58 +0000 Subject: [PATCH 2/4] Add a link to the stackexchange answer. --- Doc/library/hashlib.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst index 3d8efa099020de..653ea47f43960a 100644 --- a/Doc/library/hashlib.rst +++ b/Doc/library/hashlib.rst @@ -251,7 +251,8 @@ include a `salt `_. 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 stackexchange-pbkdf2_ explain further. *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. @@ -734,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: https://security.stackexchange.com/questions/3959/recommended-of-iterations-when-using-pbkdf2-sha256/ .. seealso:: From f8323fae53b8addfcbda59f840304eb60d509f72 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Thu, 27 Jan 2022 19:50:36 +0000 Subject: [PATCH 3/4] remove unnecessary \ escape in doc. --- Doc/library/hashlib.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst index 653ea47f43960a..6a4b9a8a8e4669 100644 --- a/Doc/library/hashlib.rst +++ b/Doc/library/hashlib.rst @@ -259,7 +259,7 @@ include a `salt `_. >>> 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 = pbkdf2_hmac('sha256', b'password', b'bad salt'*2, our_app_iters) >>> dk.hex() '15530bba69924174860db778f2c6f8104d3aaf9d26241840c8c4a641c8d000a9' From 95d0f4caf9e03840d5f396ffcb98cfe2a1ca863b Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Thu, 27 Jan 2022 19:59:57 +0000 Subject: [PATCH 4/4] improve the hyperlink text. --- Doc/library/hashlib.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst index 6a4b9a8a8e4669..aa24131f8bf444 100644 --- a/Doc/library/hashlib.rst +++ b/Doc/library/hashlib.rst @@ -252,7 +252,7 @@ include a `salt `_. 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_. The answers - on stackexchange-pbkdf2_ explain further. + 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. @@ -735,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: https://security.stackexchange.com/questions/3959/recommended-of-iterations-when-using-pbkdf2-sha256/ +.. _stackexchange pbkdf2 iterations question: https://security.stackexchange.com/questions/3959/recommended-of-iterations-when-using-pbkdf2-sha256/ .. seealso::