diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst
index d74d555c46cfa6c7c627a3f5393a14375998baaa_ZG9jcy9oYXptYXQvcHJpbWl0aXZlcy9rZXktZGVyaXZhdGlvbi1mdW5jdGlvbnMucnN0..58f4019b101f4bbf76707d174ef25136358d0e41_ZG9jcy9oYXptYXQvcHJpbWl0aXZlcy9rZXktZGVyaXZhdGlvbi1mdW5jdGlvbnMucnN0 100644
--- a/docs/hazmat/primitives/key-derivation-functions.rst
+++ b/docs/hazmat/primitives/key-derivation-functions.rst
@@ -26,6 +26,14 @@
Ideal password storage KDFs will be demanding on both computational and
memory resources.
+
+Variable cost algorithms
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+PBKDF2
+------
+
.. currentmodule:: cryptography.hazmat.primitives.kdf.pbkdf2
.. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend)
@@ -130,6 +138,318 @@
key.
+Scrypt
+------
+
+.. currentmodule:: cryptography.hazmat.primitives.kdf.scrypt
+
+.. class:: Scrypt(salt, length, n, r, p, backend)
+
+ .. versionadded:: 1.6
+
+ Scrypt is a KDF designed for password storage by Colin Percival to be
+ resistant against hardware-assisted attackers by having a tunable memory
+ cost. It is described in :rfc:`7914`.
+
+ This class conforms to the
+ :class:`~cryptography.hazmat.primitives.kdf.KeyDerivationFunction`
+ interface.
+
+ .. doctest::
+
+ >>> import os
+ >>> from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
+ >>> from cryptography.hazmat.backends import default_backend
+ >>> backend = default_backend()
+ >>> salt = os.urandom(16)
+ >>> # derive
+ >>> kdf = Scrypt(
+ ... salt=salt,
+ ... length=32,
+ ... n=2**14,
+ ... r=8,
+ ... p=1,
+ ... backend=backend
+ ... )
+ >>> key = kdf.derive(b"my great password")
+ >>> # verify
+ >>> kdf = Scrypt(
+ ... salt=salt,
+ ... length=32,
+ ... n=2**14,
+ ... r=8,
+ ... p=1,
+ ... backend=backend
+ ... )
+ >>> kdf.verify(b"my great password", key)
+
+ :param bytes salt: A salt.
+ :param int length: The desired length of the derived key in bytes.
+ :param int n: CPU/Memory cost parameter. It must be larger than 1 and be a
+ power of 2.
+ :param int r: Block size parameter.
+ :param int p: Parallelization parameter.
+ :param backend: An instance of
+ :class:`~cryptography.hazmat.backends.interfaces.ScryptBackend`.
+
+ 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`_.
+
+ :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).
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
+ provided ``backend`` does not implement
+ :class:`~cryptography.hazmat.backends.interfaces.ScryptBackend`
+
+ :raises TypeError: This exception is raised if ``salt`` is not ``bytes``.
+ :raises ValueError: This exception is raised if ``n`` is less than 2, if
+ ``n`` is not a power of 2, if ``r`` is less than 1 or if ``p`` is less
+ than 1.
+
+ .. method:: derive(key_material)
+
+ :param key_material: The input key material.
+ :type key_material: :term:`bytes-like`
+ :return bytes: the derived key.
+ :raises TypeError: This exception is raised if ``key_material`` is not
+ ``bytes``.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ This generates and returns a new key from the supplied password.
+
+ .. method:: verify(key_material, expected_key)
+
+ :param bytes key_material: The input key material. This is the same as
+ ``key_material`` in :meth:`derive`.
+ :param bytes expected_key: The expected result of deriving a new key,
+ this is the same as the return value of
+ :meth:`derive`.
+ :raises cryptography.exceptions.InvalidKey: This is raised when the
+ derived key does not match
+ the expected key.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ This checks whether deriving a new key from the supplied
+ ``key_material`` generates the same key as the ``expected_key``, and
+ raises an exception if they do not match. This can be used for
+ checking whether the password a user provides matches the stored derived
+ key.
+
+Fixed cost algorithms
+~~~~~~~~~~~~~~~~~~~~~
+
+
+ConcatKDF
+---------
+
+.. currentmodule:: cryptography.hazmat.primitives.kdf.concatkdf
+
+.. class:: ConcatKDFHash(algorithm, length, otherinfo, backend)
+
+ .. versionadded:: 1.0
+
+ ConcatKDFHash (Concatenation Key Derivation Function) is defined by the
+ NIST Special Publication `NIST SP 800-56Ar2`_ document, to be used to
+ derive keys for use after a Key Exchange negotiation operation.
+
+ .. warning::
+
+ ConcatKDFHash should not be used for password storage.
+
+ .. doctest::
+
+ >>> import os
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.kdf.concatkdf import ConcatKDFHash
+ >>> from cryptography.hazmat.backends import default_backend
+ >>> backend = default_backend()
+ >>> otherinfo = b"concatkdf-example"
+ >>> ckdf = ConcatKDFHash(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... otherinfo=otherinfo,
+ ... backend=backend
+ ... )
+ >>> key = ckdf.derive(b"input key")
+ >>> ckdf = ConcatKDFHash(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... otherinfo=otherinfo,
+ ... backend=backend
+ ... )
+ >>> ckdf.verify(b"input key", key)
+
+ :param algorithm: An instance of
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
+
+ :param int length: The desired length of the derived key in bytes.
+ Maximum is ``hashlen * (2^32 -1)``.
+
+ :param bytes otherinfo: Application specific context information.
+ If ``None`` is explicitly passed an empty byte string will be used.
+
+ :param backend: An instance of
+ :class:`~cryptography.hazmat.backends.interfaces.HashBackend`.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised
+ if the provided ``backend`` does not implement
+ :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
+
+ :raises TypeError: This exception is raised if ``otherinfo`` is not
+ ``bytes``.
+
+ .. method:: derive(key_material)
+
+ :param key_material: The input key material.
+ :type key_material: :term:`bytes-like`
+ :return bytes: The derived key.
+ :raises TypeError: This exception is raised if ``key_material`` is
+ not ``bytes``.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ Derives a new key from the input key material.
+
+ .. method:: verify(key_material, expected_key)
+
+ :param bytes key_material: The input key material. This is the same as
+ ``key_material`` in :meth:`derive`.
+ :param bytes expected_key: The expected result of deriving a new key,
+ this is the same as the return value of
+ :meth:`derive`.
+ :raises cryptography.exceptions.InvalidKey: This is raised when the
+ derived key does not match
+ the expected key.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ This checks whether deriving a new key from the supplied
+ ``key_material`` generates the same key as the ``expected_key``, and
+ raises an exception if they do not match.
+
+
+.. class:: ConcatKDFHMAC(algorithm, length, salt, otherinfo, backend)
+
+ .. versionadded:: 1.0
+
+ Similar to ConcatKFDHash but uses an HMAC function instead.
+
+ .. warning::
+
+ ConcatKDFHMAC should not be used for password storage.
+
+ .. doctest::
+
+ >>> import os
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.kdf.concatkdf import ConcatKDFHMAC
+ >>> from cryptography.hazmat.backends import default_backend
+ >>> backend = default_backend()
+ >>> salt = os.urandom(16)
+ >>> otherinfo = b"concatkdf-example"
+ >>> ckdf = ConcatKDFHMAC(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... salt=salt,
+ ... otherinfo=otherinfo,
+ ... backend=backend
+ ... )
+ >>> key = ckdf.derive(b"input key")
+ >>> ckdf = ConcatKDFHMAC(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... salt=salt,
+ ... otherinfo=otherinfo,
+ ... backend=backend
+ ... )
+ >>> ckdf.verify(b"input key", key)
+
+ :param algorithm: An instance of
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
+
+ :param int length: The desired length of the derived key in bytes. Maximum
+ is ``hashlen * (2^32 -1)``.
+
+ :param bytes salt: A salt. Randomizes the KDF's output. Optional, but
+ highly recommended. Ideally as many bits of entropy as the security
+ level of the hash: often that means cryptographically random and as
+ long as the hash output. Does not have to be secret, but may cause
+ stronger security guarantees if secret; If ``None`` is explicitly
+ passed a default salt of ``algorithm.block_size`` null bytes will be
+ used.
+
+ :param bytes otherinfo: Application specific context information.
+ If ``None`` is explicitly passed an empty byte string will be used.
+
+ :param backend: An instance of
+ :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
+ provided ``backend`` does not implement
+ :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
+
+ :raises TypeError: This exception is raised if ``salt`` or ``otherinfo``
+ is not ``bytes``.
+
+ .. method:: derive(key_material)
+
+ :param bytes key_material: The input key material.
+ :return bytes: The derived key.
+ :raises TypeError: This exception is raised if ``key_material`` is not
+ ``bytes``.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ Derives a new key from the input key material.
+
+ .. method:: verify(key_material, expected_key)
+
+ :param bytes key_material: The input key material. This is the same as
+ ``key_material`` in :meth:`derive`.
+ :param bytes expected_key: The expected result of deriving a new key,
+ this is the same as the return value of
+ :meth:`derive`.
+ :raises cryptography.exceptions.InvalidKey: This is raised when the
+ derived key does not match
+ the expected key.
+ :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+ :meth:`derive` or
+ :meth:`verify` is
+ called more than
+ once.
+
+ This checks whether deriving a new key from the supplied
+ ``key_material`` generates the same key as the ``expected_key``, and
+ raises an exception if they do not match.
+
+
+HKDF
+----
+
.. currentmodule:: cryptography.hazmat.primitives.kdf.hkdf
.. class:: HKDF(algorithm, length, salt, info, backend)
@@ -329,5 +649,4 @@
``key_material`` generates the same key as the ``expected_key``, and
raises an exception if they do not match.
-.. currentmodule:: cryptography.hazmat.primitives.kdf.concatkdf
@@ -333,289 +652,6 @@
-.. class:: ConcatKDFHash(algorithm, length, otherinfo, backend)
-
- .. versionadded:: 1.0
-
- ConcatKDFHash (Concatenation Key Derivation Function) is defined by the
- NIST Special Publication `NIST SP 800-56Ar2`_ document, to be used to
- derive keys for use after a Key Exchange negotiation operation.
-
- .. warning::
-
- ConcatKDFHash should not be used for password storage.
-
- .. doctest::
-
- >>> import os
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.kdf.concatkdf import ConcatKDFHash
- >>> from cryptography.hazmat.backends import default_backend
- >>> backend = default_backend()
- >>> otherinfo = b"concatkdf-example"
- >>> ckdf = ConcatKDFHash(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... otherinfo=otherinfo,
- ... backend=backend
- ... )
- >>> key = ckdf.derive(b"input key")
- >>> ckdf = ConcatKDFHash(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... otherinfo=otherinfo,
- ... backend=backend
- ... )
- >>> ckdf.verify(b"input key", key)
-
- :param algorithm: An instance of
- :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
-
- :param int length: The desired length of the derived key in bytes.
- Maximum is ``hashlen * (2^32 -1)``.
-
- :param bytes otherinfo: Application specific context information.
- If ``None`` is explicitly passed an empty byte string will be used.
-
- :param backend: An instance of
- :class:`~cryptography.hazmat.backends.interfaces.HashBackend`.
-
- :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised
- if the provided ``backend`` does not implement
- :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
-
- :raises TypeError: This exception is raised if ``otherinfo`` is not
- ``bytes``.
-
- .. method:: derive(key_material)
-
- :param key_material: The input key material.
- :type key_material: :term:`bytes-like`
- :return bytes: The derived key.
- :raises TypeError: This exception is raised if ``key_material`` is
- not ``bytes``.
- :raises cryptography.exceptions.AlreadyFinalized: This is raised when
- :meth:`derive` or
- :meth:`verify` is
- called more than
- once.
-
- Derives a new key from the input key material.
-
- .. method:: verify(key_material, expected_key)
-
- :param bytes key_material: The input key material. This is the same as
- ``key_material`` in :meth:`derive`.
- :param bytes expected_key: The expected result of deriving a new key,
- this is the same as the return value of
- :meth:`derive`.
- :raises cryptography.exceptions.InvalidKey: This is raised when the
- derived key does not match
- the expected key.
- :raises cryptography.exceptions.AlreadyFinalized: This is raised when
- :meth:`derive` or
- :meth:`verify` is
- called more than
- once.
-
- This checks whether deriving a new key from the supplied
- ``key_material`` generates the same key as the ``expected_key``, and
- raises an exception if they do not match.
-
-
-.. class:: ConcatKDFHMAC(algorithm, length, salt, otherinfo, backend)
-
- .. versionadded:: 1.0
-
- Similar to ConcatKFDHash but uses an HMAC function instead.
-
- .. warning::
-
- ConcatKDFHMAC should not be used for password storage.
-
- .. doctest::
-
- >>> import os
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.kdf.concatkdf import ConcatKDFHMAC
- >>> from cryptography.hazmat.backends import default_backend
- >>> backend = default_backend()
- >>> salt = os.urandom(16)
- >>> otherinfo = b"concatkdf-example"
- >>> ckdf = ConcatKDFHMAC(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... salt=salt,
- ... otherinfo=otherinfo,
- ... backend=backend
- ... )
- >>> key = ckdf.derive(b"input key")
- >>> ckdf = ConcatKDFHMAC(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... salt=salt,
- ... otherinfo=otherinfo,
- ... backend=backend
- ... )
- >>> ckdf.verify(b"input key", key)
-
- :param algorithm: An instance of
- :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
-
- :param int length: The desired length of the derived key in bytes. Maximum
- is ``hashlen * (2^32 -1)``.
-
- :param bytes salt: A salt. Randomizes the KDF's output. Optional, but
- highly recommended. Ideally as many bits of entropy as the security
- level of the hash: often that means cryptographically random and as
- long as the hash output. Does not have to be secret, but may cause
- stronger security guarantees if secret; If ``None`` is explicitly
- passed a default salt of ``algorithm.block_size`` null bytes will be
- used.
-
- :param bytes otherinfo: Application specific context information.
- If ``None`` is explicitly passed an empty byte string will be used.
-
- :param backend: An instance of
- :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`.
-
- :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
- provided ``backend`` does not implement
- :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
-
- :raises TypeError: This exception is raised if ``salt`` or ``otherinfo``
- is not ``bytes``.
-
- .. method:: derive(key_material)
-
- :param bytes key_material: The input key material.
- :return bytes: The derived key.
- :raises TypeError: This exception is raised if ``key_material`` is not
- ``bytes``.
- :raises cryptography.exceptions.AlreadyFinalized: This is raised when
- :meth:`derive` or
- :meth:`verify` is
- called more than
- once.
-
- Derives a new key from the input key material.
-
- .. method:: verify(key_material, expected_key)
-
- :param bytes key_material: The input key material. This is the same as
- ``key_material`` in :meth:`derive`.
- :param bytes expected_key: The expected result of deriving a new key,
- this is the same as the return value of
- :meth:`derive`.
- :raises cryptography.exceptions.InvalidKey: This is raised when the
- derived key does not match
- the expected key.
- :raises cryptography.exceptions.AlreadyFinalized: This is raised when
- :meth:`derive` or
- :meth:`verify` is
- called more than
- once.
-
- This checks whether deriving a new key from the supplied
- ``key_material`` generates the same key as the ``expected_key``, and
- raises an exception if they do not match.
-
-.. currentmodule:: cryptography.hazmat.primitives.kdf.x963kdf
-
-.. class:: X963KDF(algorithm, length, otherinfo, backend)
-
- .. versionadded:: 1.1
-
- X963KDF (ANSI X9.63 Key Derivation Function) is defined by ANSI
- in the `ANSI X9.63:2001`_ document, to be used to derive keys for use
- after a Key Exchange negotiation operation.
-
- SECG in `SEC 1 v2.0`_ recommends that
- :class:`~cryptography.hazmat.primitives.kdf.concatkdf.ConcatKDFHash` be
- used for new projects. This KDF should only be used for backwards
- compatibility with pre-existing protocols.
-
-
- .. warning::
-
- X963KDF should not be used for password storage.
-
- .. doctest::
-
- >>> import os
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.kdf.x963kdf import X963KDF
- >>> from cryptography.hazmat.backends import default_backend
- >>> backend = default_backend()
- >>> sharedinfo = b"ANSI X9.63 Example"
- >>> xkdf = X963KDF(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... sharedinfo=sharedinfo,
- ... backend=backend
- ... )
- >>> key = xkdf.derive(b"input key")
- >>> xkdf = X963KDF(
- ... algorithm=hashes.SHA256(),
- ... length=32,
- ... sharedinfo=sharedinfo,
- ... backend=backend
- ... )
- >>> xkdf.verify(b"input key", key)
-
- :param algorithm: An instance of
- :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
-
- :param int length: The desired length of the derived key in bytes.
- Maximum is ``hashlen * (2^32 -1)``.
-
- :param bytes sharedinfo: Application specific context information.
- If ``None`` is explicitly passed an empty byte string will be used.
-
- :param backend: A cryptography backend
- :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
- instance.
-
- :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised
- if the provided ``backend`` does not implement
- :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
-
- :raises TypeError: This exception is raised if ``sharedinfo`` is not
- ``bytes``.
-
- .. method:: derive(key_material)
-
- :param key_material: The input key material.
- :type key_material: :term:`bytes-like`
- :return bytes: The derived key.
- :raises TypeError: This exception is raised if ``key_material`` is
- not ``bytes``.
- :raises cryptography.exceptions.AlreadyFinalized: This is raised when
- :meth:`derive` or
- :meth:`verify` is
- called more than
- once.
-
- Derives a new key from the input key material.
-
- .. method:: verify(key_material, expected_key)
-
- :param bytes key_material: The input key material. This is the same as
- ``key_material`` in :meth:`derive`.
- :param bytes expected_key: The expected result of deriving a new key,
- this is the same as the return value of
- :meth:`derive`.
- :raises cryptography.exceptions.InvalidKey: This is raised when the
- derived key does not match
- the expected key.
- :raises cryptography.exceptions.AlreadyFinalized: This is raised when
- :meth:`derive` or
- :meth:`verify` is
- called more than
- once.
-
- This checks whether deriving a new key from the supplied
- ``key_material`` generates the same key as the ``expected_key``, and
- raises an exception if they do not match.
-
+KBKDF
+-----
.. currentmodule:: cryptography.hazmat.primitives.kdf.kbkdf
@@ -771,5 +807,7 @@
The counter iteration variable will be concatenated after
the fixed input data.
-.. currentmodule:: cryptography.hazmat.primitives.kdf.scrypt
+
+X963KDF
+-------
@@ -775,3 +813,3 @@
-.. class:: Scrypt(salt, length, n, r, p, backend)
+.. currentmodule:: cryptography.hazmat.primitives.kdf.x963kdf
@@ -777,3 +815,5 @@
- .. versionadded:: 1.6
+.. class:: X963KDF(algorithm, length, otherinfo, backend)
+
+ .. versionadded:: 1.1
@@ -779,5 +819,5 @@
- Scrypt is a KDF designed for password storage by Colin Percival to be
- resistant against hardware-assisted attackers by having a tunable memory
- cost. It is described in :rfc:`7914`.
+ X963KDF (ANSI X9.63 Key Derivation Function) is defined by ANSI
+ in the `ANSI X9.63:2001`_ document, to be used to derive keys for use
+ after a Key Exchange negotiation operation.
@@ -783,8 +823,14 @@
- This class conforms to the
- :class:`~cryptography.hazmat.primitives.kdf.KeyDerivationFunction`
- interface.
+ SECG in `SEC 1 v2.0`_ recommends that
+ :class:`~cryptography.hazmat.primitives.kdf.concatkdf.ConcatKDFHash` be
+ used for new projects. This KDF should only be used for backwards
+ compatibility with pre-existing protocols.
+
+
+ .. warning::
+
+ X963KDF should not be used for password storage.
.. doctest::
>>> import os
@@ -787,7 +833,8 @@
.. doctest::
>>> import os
- >>> from cryptography.hazmat.primitives.kdf.scrypt import Scrypt
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.kdf.x963kdf import X963KDF
>>> from cryptography.hazmat.backends import default_backend
>>> backend = default_backend()
@@ -792,7 +839,6 @@
>>> from cryptography.hazmat.backends import default_backend
>>> backend = default_backend()
- >>> salt = os.urandom(16)
- >>> # derive
- >>> kdf = Scrypt(
- ... salt=salt,
+ >>> sharedinfo = b"ANSI X9.63 Example"
+ >>> xkdf = X963KDF(
+ ... algorithm=hashes.SHA256(),
... length=32,
@@ -798,6 +844,4 @@
... length=32,
- ... n=2**14,
- ... r=8,
- ... p=1,
+ ... sharedinfo=sharedinfo,
... backend=backend
... )
@@ -802,7 +846,6 @@
... backend=backend
... )
- >>> key = kdf.derive(b"my great password")
- >>> # verify
- >>> kdf = Scrypt(
- ... salt=salt,
+ >>> key = xkdf.derive(b"input key")
+ >>> xkdf = X963KDF(
+ ... algorithm=hashes.SHA256(),
... length=32,
@@ -808,6 +851,4 @@
... length=32,
- ... n=2**14,
- ... r=8,
- ... p=1,
+ ... sharedinfo=sharedinfo,
... backend=backend
... )
@@ -812,4 +853,4 @@
... backend=backend
... )
- >>> kdf.verify(b"my great password", key)
+ >>> xkdf.verify(b"input key", key)
@@ -815,3 +856,5 @@
- :param bytes salt: A salt.
+ :param algorithm: An instance of
+ :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
+
:param int length: The desired length of the derived key in bytes.
@@ -817,8 +860,6 @@
:param int length: The desired length of the derived key in bytes.
- :param int n: CPU/Memory cost parameter. It must be larger than 1 and be a
- power of 2.
- :param int r: Block size parameter.
- :param int p: Parallelization parameter.
- :param backend: An instance of
- :class:`~cryptography.hazmat.backends.interfaces.ScryptBackend`.
+ Maximum is ``hashlen * (2^32 -1)``.
+
+ :param bytes sharedinfo: Application specific context information.
+ If ``None`` is explicitly passed an empty byte string will be used.
@@ -824,8 +865,5 @@
- 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`_.
+ :param backend: A cryptography backend
+ :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
+ instance.
@@ -831,6 +869,5 @@
- :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).
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised
+ if the provided ``backend`` does not implement
+ :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
@@ -836,14 +873,8 @@
- :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
- provided ``backend`` does not implement
- :class:`~cryptography.hazmat.backends.interfaces.ScryptBackend`
-
- :raises TypeError: This exception is raised if ``salt`` is not ``bytes``.
- :raises ValueError: This exception is raised if ``n`` is less than 2, if
- ``n`` is not a power of 2, if ``r`` is less than 1 or if ``p`` is less
- than 1.
+ :raises TypeError: This exception is raised if ``sharedinfo`` is not
+ ``bytes``.
.. method:: derive(key_material)
:param key_material: The input key material.
:type key_material: :term:`bytes-like`
@@ -845,14 +876,14 @@
.. method:: derive(key_material)
:param key_material: The input key material.
:type key_material: :term:`bytes-like`
- :return bytes: the derived key.
- :raises TypeError: This exception is raised if ``key_material`` is not
- ``bytes``.
+ :return bytes: The derived key.
+ :raises TypeError: This exception is raised if ``key_material`` is
+ not ``bytes``.
:raises cryptography.exceptions.AlreadyFinalized: This is raised when
:meth:`derive` or
:meth:`verify` is
called more than
once.
@@ -853,10 +884,10 @@
:raises cryptography.exceptions.AlreadyFinalized: This is raised when
:meth:`derive` or
:meth:`verify` is
called more than
once.
- This generates and returns a new key from the supplied password.
+ Derives a new key from the input key material.
.. method:: verify(key_material, expected_key)
@@ -876,9 +907,8 @@
This checks whether deriving a new key from the supplied
``key_material`` generates the same key as the ``expected_key``, and
- raises an exception if they do not match. This can be used for
- checking whether the password a user provides matches the stored derived
- key.
+ raises an exception if they do not match.
+
Interface
~~~~~~~~~