aboutsummaryrefslogtreecommitdiffstats
path: root/docs/hazmat/primitives/key-derivation-functions.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/hazmat/primitives/key-derivation-functions.rst')
-rw-r--r--docs/hazmat/primitives/key-derivation-functions.rst107
1 files changed, 106 insertions, 1 deletions
diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst
index 269f949d..f68b12c1 100644
--- a/docs/hazmat/primitives/key-derivation-functions.rst
+++ b/docs/hazmat/primitives/key-derivation-functions.rst
@@ -88,6 +88,8 @@ Different KDFs are suitable for different tasks such as:
provided ``backend`` does not implement
:class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend`
+ :raises TypeError: This exception is raised if ``salt`` is not ``bytes``.
+
.. method:: derive(key_material)
:param bytes key_material: The input key material. For PBKDF2 this
@@ -99,6 +101,9 @@ Different KDFs are suitable for different tasks such as:
called more than
once.
+ :raises TypeError: This exception is raised if ``key_material`` is not
+ ``bytes``.
+
This generates and returns a new key from the supplied password.
.. method:: verify(key_material, expected_key)
@@ -191,10 +196,108 @@ Different KDFs are suitable for different tasks such as:
provided ``backend`` does not implement
:class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
+ :raises TypeError: This exception is raised if ``salt`` or ``info`` 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``.
+
+ Derives a new key from the input key material by performing both the
+ extract and expand operations.
+
+ .. method:: verify(key_material, expected_key)
+
+ :param key_material bytes: The input key material. This is the same as
+ ``key_material`` in :meth:`derive`.
+ :param expected_key bytes: 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:: HKDFExpand(algorithm, length, info, backend)
+
+ .. versionadded:: 0.5
+
+ HKDF consists of two stages, extract and expand. This class exposes an
+ expand only version of HKDF that is suitable when the key material is
+ already cryptographically strong.
+
+ .. warning::
+
+ HKDFExpand should only be used if the key material is
+ cryptographically strong. You should use
+ :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF` if
+ you are unsure.
+
+ .. doctest::
+
+ >>> import os
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDFExpand
+ >>> from cryptography.hazmat.backends import default_backend
+ >>> backend = default_backend()
+ >>> info = b"hkdf-example"
+ >>> key_material = os.urandom(16)
+ >>> hkdf = HKDFExpand(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... info=info,
+ ... backend=backend
+ ... )
+ >>> key = hkdf.derive(key_material)
+ >>> hkdf = HKDFExpand(
+ ... algorithm=hashes.SHA256(),
+ ... length=32,
+ ... info=info,
+ ... backend=backend
+ ... )
+ >>> hkdf.verify(key_material, key)
+
+ :param algorithm: An instance of a
+ :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+ provider.
+
+ :param int length: The desired length of the derived key. Maximum is
+ ``255 * (algorithm.digest_size // 8)``.
+
+ :param bytes info: Application specific context information. If ``None``
+ is explicitly passed an empty byte string will be used.
+
+ :param backend: A
+ :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
+ provider.
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
+ provided ``backend`` does not implement
+ :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
+ :raises TypeError: This is raised if the provided ``info`` is a unicode object
+ :raises TypeError: This exception is raised if ``info`` is not ``bytes``.
+
.. method:: derive(key_material)
:param bytes key_material: The input key material.
- :retunr bytes: The derived key.
+ :return bytes: The derived key.
+
+ :raises TypeError: This is raised if the provided ``key_material`` is
+ a unicode object
+ :raises TypeError: This exception is raised if ``key_material`` is not
+ ``bytes``.
Derives a new key from the input key material by performing both the
extract and expand operations.
@@ -214,6 +317,8 @@ Different KDFs are suitable for different tasks such as:
:meth:`verify` is
called more than
once.
+ :raises TypeError: This is raised if the provided ``key_material`` is
+ a unicode object
This checks whether deriving a new key from the supplied
``key_material`` generates the same key as the ``expected_key``, and