Scrypt docs code example contradict RFC 7914 (#3302) (#3303)
* Scrypt docs code example contradict RFC 7914 (#3302)
* More secure example difficulty of parameter n in scrypt docs (#3302)
* Change link text to scrypt paper (#3302)
* Change link text to scrypt paper, part deux (#3302)
* Add "logins" to spelling wordlist
diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst
index dbca3a5..607eeb2 100644
--- a/docs/hazmat/primitives/key-derivation-functions.rst
+++ b/docs/hazmat/primitives/key-derivation-functions.rst
@@ -755,7 +755,6 @@
.. code-block:: python
>>> import os
- >>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
>>> from cryptography.hazmat.backends import default_backend
>>> backend = default_backend()
@@ -764,9 +763,9 @@
>>> kdf = Scrypt(
... salt=salt,
... length=64,
- ... n=1024,
+ ... n=2**14,
... r=8,
- ... p=16,
+ ... p=1,
... backend=backend
... )
>>> key = kdf.derive(b"my great password")
@@ -774,9 +773,9 @@
>>> kdf = Scrypt(
... salt=salt,
... length=64,
- ... n=1024,
+ ... n=2**14,
... r=8,
- ... p=16,
+ ... p=1,
... backend=backend
... )
>>> kdf.verify(b"my great password", key)
@@ -789,14 +788,16 @@
:param int p: Parallelization parameter.
The computational and memory cost of Scrypt can be adjusted by manipulating
- the 3 parameters: n, r and p. In general, the memory cost of Scrypt is
- affected by the values of both n and r while n also determines the number
- of iterations performed. p increases the computational cost without
- affecting memory usage. A more in-depth explanation of the 3 parameters can
- be found `here`_.
+ the 3 parameters: ``n``, ``r``, and ``p``. In general, the memory cost of
+ Scrypt is affected by the values of both ``n`` and ``r``, while ``n`` also
+ determines the number of iterations performed. ``p`` increases the
+ computational cost without affecting memory usage. A more in-depth
+ explanation of the 3 parameters can be found `here`_.
- :rfc:`7914` `recommends`_ values of r=8 and p=1 while scaling n to the
- number appropriate for your system.
+ :rfc:`7914` `recommends`_ values of ``r=8`` and ``p=1`` while scaling ``n``
+ to a number appropriate for your system. `The scrypt paper`_ suggests a
+ minimum value of ``n=2**14`` for interactive logins (t < 100ms), or
+ ``n=2**20`` for more sensitive files (t < 5s).
:param backend: An instance of
:class:`~cryptography.hazmat.backends.interfaces.ScryptBackend`.
@@ -905,3 +906,4 @@
.. _`HKDF paper`: https://eprint.iacr.org/2010/264
.. _`here`: https://stackoverflow.com/a/30308723/1170681
.. _`recommends`: https://tools.ietf.org/html/rfc7914#section-2
+.. _`The scrypt paper`: https://www.tarsnap.com/scrypt/scrypt.pdf
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index d57c4d2..13d5e07 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -49,6 +49,7 @@
iterable
Koblitz
Lange
+logins
metadata
Mozilla
multi