From ee3e6bf35d482df4af4b7fdf9804df71e62d4717 Mon Sep 17 00:00:00 2001 From: Alex Stapleton Date: Sun, 2 Feb 2014 21:13:48 +0000 Subject: Rename RSAs key_length to key_size So that it matches the existing documented CipherContext stuff. --- docs/hazmat/primitives/interfaces.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 09a5a4ce..7fef1c13 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -130,7 +130,7 @@ Asymmetric Interfaces The public exponent. - .. attribute:: key_length + .. attribute:: key_size :type: int @@ -179,7 +179,7 @@ Asymmetric Interfaces The public modulus. - .. attribute:: key_length + .. attribute:: key_size :type: int -- cgit v1.2.3 From 2649a694961a74126d977d8780d3d2fa2587e4e4 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 3 Feb 2014 07:14:16 -0800 Subject: Refer to the `d` param of RSA as `private_exponent`. --- docs/hazmat/primitives/interfaces.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 7fef1c13..cbca5ed6 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -130,6 +130,12 @@ Asymmetric Interfaces The public exponent. + .. attribute:: private_exponent + + :type: int + + The private exponent. + .. attribute:: key_size :type: int @@ -152,7 +158,7 @@ Asymmetric Interfaces :type: int - The private exponent. + The private exponent. Alias for :attr:`private_exponent`. .. attribute:: n -- cgit v1.2.3 From c0248b9be0a207fe1b27690d819bd79ac3e1aa84 Mon Sep 17 00:00:00 2001 From: David Reid Date: Thu, 30 Jan 2014 15:23:33 -0800 Subject: HKDF docs --- .../hazmat/primitives/key-derivation-functions.rst | 66 +++++++++++++++++++++- 1 file changed, 65 insertions(+), 1 deletion(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index f96eae06..678d13bf 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -13,7 +13,8 @@ Different KDFs are suitable for different tasks such as: Deriving a key suitable for use as input to an encryption algorithm. Typically this means taking a password and running it through an algorithm - such as :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC` or HKDF. + such as :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC` or + :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`. This process is typically known as `key stretching`_. * Password storage @@ -118,8 +119,71 @@ Different KDFs are suitable for different tasks such as: checking whether the password a user provides matches the stored derived key. + +.. currentmodule:: cryptography.hazmat.primitives.kdf.hkdf + +.. class:: HKDF(algorithm, length, salt, info, backend) + + .. versionadded:: 0.2 + + `HKDF`_ (HMAC-based Extract-and-Expand Key Derivation Function) suitable + for deriving keys of a fixed size used for other cryptographic operations. + + It consists of two distinct phases "Extract" and "Expand". The "Extract" + stage takes a low-entropy key and extracts from it a fixed size + psuedorandom key. The "Expand" stage derives a large key of a user + determined size from the psuedorandom 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 salt: A salt. If ``None`` is explicitly passed a default salt + of ``algorithm.digest_size // 8`` null bytes. + + :param bytes info: Application specific context information. If ``None`` + is explicitly passed an empty byte string will be used. + + :params backend: A + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + provider. + + .. method:: derive(key_material) + + :param bytes key_material: The input key material. + :retunr bytes: The derived key. + + 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. This can be used for + checking whether the password a user provides matches the stored derived + key. + .. _`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`: http://en.wikipedia.org/wiki/PBKDF2 .. _`scrypt`: http://en.wikipedia.org/wiki/Scrypt .. _`key stretching`: http://en.wikipedia.org/wiki/Key_stretching +.. _`HKDF`: http://tools.ietf.org/html/rfc5869 -- cgit v1.2.3 From 2ad94ab70b03a8edc21163a6c66fbe6a49e80715 Mon Sep 17 00:00:00 2001 From: David Reid Date: Mon, 3 Feb 2014 10:01:15 -0800 Subject: Clarify salt language and link to the paper in addition to the RFC. --- docs/hazmat/primitives/key-derivation-functions.rst | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 678d13bf..df956326 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -126,7 +126,7 @@ Different KDFs are suitable for different tasks such as: .. versionadded:: 0.2 - `HKDF`_ (HMAC-based Extract-and-Expand Key Derivation Function) suitable + `HKDF`_ (HMAC-based Extract-and-Expand Key Derivation Function) is suitable for deriving keys of a fixed size used for other cryptographic operations. It consists of two distinct phases "Extract" and "Expand". The "Extract" @@ -141,8 +141,15 @@ Different KDFs are suitable for different tasks such as: :param int length: The desired length of the derived key. Maximum is 255 * (``algorithm.digest_size`` // 8). - :param bytes salt: A salt. If ``None`` is explicitly passed a default salt - of ``algorithm.digest_size // 8`` null bytes. + :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. Worse (shorter, less entropy) salt values can + still meaningfully contribute to security. May be reused. Does not have + to be secret, but may cause stronger security guarantees if secret; see + `RFC 5869`_ and the `HKDF paper`_ for more details. If ``None`` is + explicitly passed a default salt of ``algorithm.digest_size // 8`` null + bytes will be used. :param bytes info: Application specific context information. If ``None`` is explicitly passed an empty byte string will be used. @@ -186,4 +193,6 @@ Different KDFs are suitable for different tasks such as: .. _`PBKDF2`: http://en.wikipedia.org/wiki/PBKDF2 .. _`scrypt`: http://en.wikipedia.org/wiki/Scrypt .. _`key stretching`: http://en.wikipedia.org/wiki/Key_stretching -.. _`HKDF`: http://tools.ietf.org/html/rfc5869 +.. _`HKDF`: +.. _`RFC 5869`: http://tools.ietf.org/html/rfc5869 +.. _`HKDF paper`: http://eprint.iacr.org/2010/264 -- cgit v1.2.3 From b89f34cea6e568860ea85a3f715d04e21123d5b2 Mon Sep 17 00:00:00 2001 From: David Reid Date: Mon, 3 Feb 2014 10:01:42 -0800 Subject: Backtick the entire equation. --- docs/hazmat/primitives/key-derivation-functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index df956326..325a60b3 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -139,7 +139,7 @@ Different KDFs are suitable for different tasks such as: provider. :param int length: The desired length of the derived key. Maximum is - 255 * (``algorithm.digest_size`` // 8). + ``255 * (algorithm.digest_size // 8)``. :param bytes salt: A salt. Randomizes the KDF's output. Optional, but highly recommended. Ideally as many bits of entropy as the security -- cgit v1.2.3 From 34ed26f3f4a1d53a885ed1d7b56cae92b4a6b7a8 Mon Sep 17 00:00:00 2001 From: David Reid Date: Mon, 3 Feb 2014 10:03:58 -0800 Subject: Pseudorandom is a word. --- docs/hazmat/primitives/key-derivation-functions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 325a60b3..3c9b501e 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -131,8 +131,8 @@ Different KDFs are suitable for different tasks such as: It consists of two distinct phases "Extract" and "Expand". The "Extract" stage takes a low-entropy key and extracts from it a fixed size - psuedorandom key. The "Expand" stage derives a large key of a user - determined size from the psuedorandom key. + pseudorandom key. The "Expand" stage derives a large key of a user + determined size from the pseudorandom key. :param algorithm: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` -- cgit v1.2.3 From b80deea4bf341e2c4a283f24fec1958824195ef7 Mon Sep 17 00:00:00 2001 From: David Reid Date: Mon, 3 Feb 2014 10:33:16 -0800 Subject: https a bunch of links. --- docs/hazmat/primitives/key-derivation-functions.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 3c9b501e..b74dc41a 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -190,9 +190,9 @@ Different KDFs are suitable for different tasks such as: .. _`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`: http://en.wikipedia.org/wiki/PBKDF2 -.. _`scrypt`: http://en.wikipedia.org/wiki/Scrypt -.. _`key stretching`: http://en.wikipedia.org/wiki/Key_stretching +.. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2 +.. _`scrypt`: https://en.wikipedia.org/wiki/Scrypt +.. _`key stretching`: https://en.wikipedia.org/wiki/Key_stretching .. _`HKDF`: -.. _`RFC 5869`: http://tools.ietf.org/html/rfc5869 -.. _`HKDF paper`: http://eprint.iacr.org/2010/264 +.. _`RFC 5869`: https://tools.ietf.org/html/rfc5869 +.. _`HKDF paper`: https://eprint.iacr.org/2010/264 -- cgit v1.2.3 From b9fa7712a751c4b54dd4b9ba54552a66cc89a34e Mon Sep 17 00:00:00 2001 From: David Reid Date: Mon, 3 Feb 2014 10:45:11 -0800 Subject: Lose the bit about passwords. --- docs/hazmat/primitives/key-derivation-functions.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index b74dc41a..5c3485cc 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -184,9 +184,7 @@ Different KDFs are suitable for different tasks such as: 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. .. _`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 -- cgit v1.2.3 From 26339c580801b1e893f48c3b23eb14da8655dfbb Mon Sep 17 00:00:00 2001 From: David Reid Date: Mon, 3 Feb 2014 13:14:21 -0800 Subject: Remove language about the separate stages of HKDF until we expose multiple stages of HKDF. --- docs/hazmat/primitives/key-derivation-functions.rst | 5 ----- 1 file changed, 5 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 5c3485cc..48a066c9 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -129,11 +129,6 @@ Different KDFs are suitable for different tasks such as: `HKDF`_ (HMAC-based Extract-and-Expand Key Derivation Function) is suitable for deriving keys of a fixed size used for other cryptographic operations. - It consists of two distinct phases "Extract" and "Expand". The "Extract" - stage takes a low-entropy key and extracts from it a fixed size - pseudorandom key. The "Expand" stage derives a large key of a user - determined size from the pseudorandom key. - :param algorithm: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider. -- cgit v1.2.3 From 5df929ce2dea053626af4f8b3c3b98b81b359bda Mon Sep 17 00:00:00 2001 From: David Reid Date: Mon, 3 Feb 2014 13:26:15 -0800 Subject: HKDF example. --- .../hazmat/primitives/key-derivation-functions.rst | 26 ++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 48a066c9..a91d8ca9 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -129,6 +129,32 @@ Different KDFs are suitable for different tasks such as: `HKDF`_ (HMAC-based Extract-and-Expand Key Derivation Function) is suitable for deriving keys of a fixed size used for other cryptographic operations. + .. doctest:: + + >>> import os + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF + >>> from cryptography.hazmat.backends import default_backend + >>> backend = default_backend() + >>> salt = os.urandom(16) + >>> info = b"hkdf-example" + >>> hkdf = HKDF( + ... algorithm=hashes.SHA256(), + ... length=32, + ... salt=salt, + ... info=info, + ... backend=backend + ... ) + >>> key = hkdf.derive(b"input key) + >>> hkdf = HKDF( + ... algorithm=hashes.SHA256(), + ... length=32, + ... salt=salt, + ... info=info, + ... backend=backend + ... ) + >>> hkdf.verify(b"input key", key) + :param algorithm: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider. -- cgit v1.2.3 From 134f1f4acf423c3546b9552a169d10d40dd5fc84 Mon Sep 17 00:00:00 2001 From: David Reid Date: Mon, 3 Feb 2014 13:54:30 -0800 Subject: Strings have quote marks at both ends. --- docs/hazmat/primitives/key-derivation-functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index a91d8ca9..1937c2ec 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -145,7 +145,7 @@ Different KDFs are suitable for different tasks such as: ... info=info, ... backend=backend ... ) - >>> key = hkdf.derive(b"input key) + >>> key = hkdf.derive(b"input key") >>> hkdf = HKDF( ... algorithm=hashes.SHA256(), ... length=32, -- cgit v1.2.3