diff options
author | Alex Stapleton <alexs@prol.etari.at> | 2014-05-10 10:28:17 +0100 |
---|---|---|
committer | Alex Stapleton <alexs@prol.etari.at> | 2014-05-10 10:28:17 +0100 |
commit | 9263d5ff5e62ce4adf5d959fecb3b1115f8216cc (patch) | |
tree | de0d349e8d55b1bdbd84b6b0e0b1877e6c481922 /docs | |
parent | 92da8bb65913f366656c104ef95c44c9931eaf32 (diff) | |
parent | c48100a9126990552197b5431d22f7a9e065baf7 (diff) | |
download | cryptography-9263d5ff5e62ce4adf5d959fecb3b1115f8216cc.tar.gz cryptography-9263d5ff5e62ce4adf5d959fecb3b1115f8216cc.tar.bz2 cryptography-9263d5ff5e62ce4adf5d959fecb3b1115f8216cc.zip |
Merge pull request #1016 from Ayrx/hkdf-expand-only
HKDF Expand Only implementation
Diffstat (limited to 'docs')
-rw-r--r-- | docs/hazmat/primitives/key-derivation-functions.rst | 92 |
1 files changed, 92 insertions, 0 deletions
diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index ee8f8ab6..de6bf5f8 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -219,6 +219,98 @@ Different KDFs are suitable for different tasks such as: ``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 + + .. method:: derive(key_material) + + :param bytes key_material: The input key material. + :return bytes: The derived key. + + :raises TypeError: This is raised if the provided ``key_material`` is + a unicode object + + 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. + :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 + raises an exception if they do not match. + .. _`NIST SP 800-132`: http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf .. _`Password Storage Cheat Sheet`: https://www.owasp.org/index.php/Password_Storage_Cheat_Sheet .. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2 |