From ac423232f884b94a24257e80ac95cccd5749ba9f Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 25 Jan 2014 14:13:09 -0600 Subject: RSA private/public key interface + docs --- docs/hazmat/primitives/interfaces.rst | 100 ++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index edb24cd9..40b49a54 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -102,3 +102,103 @@ Interfaces used by the symmetric cipher modes described in Exact requirements of the nonce are described by the documentation of individual modes. + +Asymmetric Interfaces +~~~~~~~~~~~~~~~~~~~~~ + +.. class:: RSAPrivateKey + + An `RSA`_ private key. + + .. attribute:: public_key + + :type: :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` + + An RSA public key object corresponding to the values of the private key. + + .. attribute:: modulus + + :type: str + + Hexadecimal representation of the public modulus. Alias for ``n``. + + .. attribute:: public_exponent + + :type: int + + The public exponent. Alias for ``e``. + + .. attribute:: key_length + + :type: int + + The bit length of the modulus. + + .. attribute:: p + + :type: str + + Hexadecimal representation of ``p``, one of the two primes composing + ``n``. + + .. attribute:: q + + :type: str + + Hexadecimal representation of ``q``, one of the two primes composing + ``n``. + + .. attribute:: d + + :type: str + + Hexadecimal representation of ``d``, the private exponent. + + .. attribute:: n + + :type: str + + Hexadecimal representation of the public modulus. + + .. attribute:: e + + :type: int + + The public exponent. + + +.. class:: RSAPublicKey + + An `RSA`_ public key. + + .. attribute:: modulus + + :type: str + + Hexadecimal representation of the public modulus. Alias for ``n``. + + .. attribute:: key_length + + :type: int + + The bit length of the modulus. + + .. attribute:: public_exponent + + :type: int + + The public exponent. Alias for ``e``. + + .. attribute:: n + + :type: str + + Hexadecimal representation of the public modulus. + + .. attribute:: e + + :type: int + + The public exponent. + +.. _`RSA`: http://en.wikipedia.org/wiki/RSA_(cryptosystem) -- cgit v1.2.3 From d527b30d2f4515ea8d2c9af7fe7317dcab276aff Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 26 Jan 2014 11:41:38 -0600 Subject: update interface docs to make attributes return int (per irc discussion) --- docs/hazmat/primitives/interfaces.rst | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 40b49a54..c2d4c53d 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -118,9 +118,9 @@ Asymmetric Interfaces .. attribute:: modulus - :type: str + :type: int - Hexadecimal representation of the public modulus. Alias for ``n``. + The public modulus. Alias for ``n``. .. attribute:: public_exponent @@ -136,29 +136,27 @@ Asymmetric Interfaces .. attribute:: p - :type: str + :type: int - Hexadecimal representation of ``p``, one of the two primes composing - ``n``. + ``p``, one of the two primes composing ``n``. .. attribute:: q - :type: str + :type: int - Hexadecimal representation of ``q``, one of the two primes composing - ``n``. + ``q``, one of the two primes composing ``n``. .. attribute:: d - :type: str + :type: int - Hexadecimal representation of ``d``, the private exponent. + The private exponent. .. attribute:: n - :type: str + :type: int - Hexadecimal representation of the public modulus. + The public modulus. .. attribute:: e @@ -173,9 +171,9 @@ Asymmetric Interfaces .. attribute:: modulus - :type: str + :type: int - Hexadecimal representation of the public modulus. Alias for ``n``. + The public modulus. Alias for ``n``. .. attribute:: key_length @@ -191,9 +189,9 @@ Asymmetric Interfaces .. attribute:: n - :type: str + :type: int - Hexadecimal representation of the public modulus. + The public modulus. .. attribute:: e -- cgit v1.2.3 From 0e94fbe27e3942620906b7f275fa69c55defacd5 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 26 Jan 2014 11:47:21 -0600 Subject: make public_key an abstractmethod, update docs --- docs/hazmat/primitives/interfaces.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index c2d4c53d..02ba10e2 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -110,7 +110,7 @@ Asymmetric Interfaces An `RSA`_ private key. - .. attribute:: public_key + .. method:: public_key() :type: :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` @@ -120,13 +120,13 @@ Asymmetric Interfaces :type: int - The public modulus. Alias for ``n``. + The public modulus. .. attribute:: public_exponent :type: int - The public exponent. Alias for ``e``. + The public exponent. .. attribute:: key_length @@ -156,13 +156,13 @@ Asymmetric Interfaces :type: int - The public modulus. + The public modulus. Alias for ``modulus``. .. attribute:: e :type: int - The public exponent. + The public exponent. Alias for ``public_exponent``. .. class:: RSAPublicKey @@ -173,7 +173,7 @@ Asymmetric Interfaces :type: int - The public modulus. Alias for ``n``. + The public modulus. .. attribute:: key_length @@ -185,18 +185,18 @@ Asymmetric Interfaces :type: int - The public exponent. Alias for ``e``. + The public exponent. .. attribute:: n :type: int - The public modulus. + The public modulus. Alias for ``modulus``. .. attribute:: e :type: int - The public exponent. + The public exponent. Alias for ``public_exponent``. .. _`RSA`: http://en.wikipedia.org/wiki/RSA_(cryptosystem) -- cgit v1.2.3 From 359b94631c3380e2f86cf1f8e95090f7a350438f Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 26 Jan 2014 12:03:05 -0600 Subject: methods don't have a type, they return things --- docs/hazmat/primitives/interfaces.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 02ba10e2..57a84120 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -112,7 +112,7 @@ Asymmetric Interfaces .. method:: public_key() - :type: :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` + :return: :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` An RSA public key object corresponding to the values of the private key. -- cgit v1.2.3 From 82629f4adc8bfc8899b2b99915fad61b95e17fe6 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 26 Jan 2014 12:25:02 -0600 Subject: adding versionadded --- docs/hazmat/primitives/interfaces.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 57a84120..0c193bd5 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -108,6 +108,8 @@ Asymmetric Interfaces .. class:: RSAPrivateKey +.. versionadded:: 0.2 + An `RSA`_ private key. .. method:: public_key() @@ -167,6 +169,8 @@ Asymmetric Interfaces .. class:: RSAPublicKey +.. versionadded:: 0.2 + An `RSA`_ public key. .. attribute:: modulus -- cgit v1.2.3 From 46688b11ed7b4f8c53a61feb1bf355a38d3e939c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 26 Jan 2014 13:23:13 -0600 Subject: indentation is fun --- 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 0c193bd5..4739680a 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -108,7 +108,7 @@ Asymmetric Interfaces .. class:: RSAPrivateKey -.. versionadded:: 0.2 + .. versionadded:: 0.2 An `RSA`_ private key. @@ -169,7 +169,7 @@ Asymmetric Interfaces .. class:: RSAPublicKey -.. versionadded:: 0.2 + .. versionadded:: 0.2 An `RSA`_ public key. -- cgit v1.2.3 From 2a9187492c105636b92a58e9b470a8f5db6e4e81 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 26 Jan 2014 16:53:44 -0600 Subject: Linkify the RSA docs --- docs/hazmat/primitives/interfaces.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 4739680a..bf78e367 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -140,13 +140,13 @@ Asymmetric Interfaces :type: int - ``p``, one of the two primes composing ``n``. + ``p``, one of the two primes composing the :attr:`modulus`. .. attribute:: q :type: int - ``q``, one of the two primes composing ``n``. + ``q``, one of the two primes composing the :attr:`modulus`. .. attribute:: d @@ -158,13 +158,13 @@ Asymmetric Interfaces :type: int - The public modulus. Alias for ``modulus``. + The public modulus. Alias for :attr:`modulus`. .. attribute:: e :type: int - The public exponent. Alias for ``public_exponent``. + The public exponent. Alias for :attr:`public_exponent`. .. class:: RSAPublicKey @@ -195,12 +195,13 @@ Asymmetric Interfaces :type: int - The public modulus. Alias for ``modulus``. + The public modulus. Alias for :attr:`modulus`. .. attribute:: e :type: int - The public exponent. Alias for ``public_exponent``. + The public exponent. Alias for :attr:`public_exponent`. + .. _`RSA`: http://en.wikipedia.org/wiki/RSA_(cryptosystem) -- cgit v1.2.3 From b2774f53bc5840ae7c414ee78bef654a2ae89f01 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 27 Jan 2014 11:05:29 -0800 Subject: Begin designing the KDF interfaces. Fixes #511 --- docs/hazmat/primitives/interfaces.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index bf78e367..ac48dd2c 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -204,4 +204,34 @@ Asymmetric Interfaces The public exponent. Alias for :attr:`public_exponent`. +Key Derivation Functions +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: KeyDerivationFunction + + .. method:: derive(key_material) + + :param key_material bytes: The raw key material. Depending on what key + derivation function you are using this could + be either random material, or a user + supplied password. + :return: The resulting key. + + The generates and returns a new key from the supplied key material. + + .. method:: verify(key_material, expected_key) + + :param key_material bytes: The raw key material. This is the same as + ``key_material`` in :meth:`derive`. + :param expected_key bytes: What the expected result of deriving a new + key is. + :raises cryptography.exceptions.InvalidKey: This is raised when the + derived key does not match + the expected key. + + This checks whether deriving a 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 something like checking + whether a user's password attempt matches the stored derived key. + .. _`RSA`: http://en.wikipedia.org/wiki/RSA_(cryptosystem) -- cgit v1.2.3 From 5484f72a8f83b8488bd22cae98be7c0c3576991a Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 28 Jan 2014 05:46:15 -0800 Subject: Try to improve the docs --- docs/hazmat/primitives/interfaces.rst | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index ac48dd2c..ddccb773 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -211,27 +211,29 @@ Key Derivation Functions .. method:: derive(key_material) - :param key_material bytes: The raw key material. Depending on what key - derivation function you are using this could - be either random material, or a user + :param key_material bytes: The input key material. Depending on what + key derivation function you are using this + could be either random material, or a user supplied password. - :return: The resulting key. + :return: The new key. - The generates and returns a new key from the supplied key material. + This generates and returns a new key from the supplied key material. .. method:: verify(key_material, expected_key) - :param key_material bytes: The raw key material. This is the same as + :param key_material bytes: The input key material. This is the same as ``key_material`` in :meth:`derive`. - :param expected_key bytes: What the expected result of deriving a new - key is. + :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. - This checks whether deriving a 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 something like checking - whether a user's password attempt matches the stored derived key. + 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 + something like checking whether a user's password attempt matches the + stored derived key. .. _`RSA`: http://en.wikipedia.org/wiki/RSA_(cryptosystem) -- cgit v1.2.3 From e19e89f3e29c057a8250f5f63dde444b495259f7 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 28 Jan 2014 06:58:43 -0800 Subject: Enforce that these may only be called once --- docs/hazmat/primitives/interfaces.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index ddccb773..12644f4c 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -216,6 +216,11 @@ Key Derivation Functions could be either random material, or a user supplied password. :return: The new key. + :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 key material. @@ -229,6 +234,11 @@ Key Derivation Functions :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 -- cgit v1.2.3 From 8454c5153537439b36b879e82ab3a3d8e7aa7909 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 28 Jan 2014 07:01:54 -0800 Subject: Document that this is new in 0.2 --- docs/hazmat/primitives/interfaces.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 12644f4c..2adad913 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -209,6 +209,8 @@ Key Derivation Functions .. class:: KeyDerivationFunction + .. versionadded:: 0.2 + .. method:: derive(key_material) :param key_material bytes: The input key material. Depending on what -- cgit v1.2.3 From b6d764c3f28837ed8854dfa836029a0b4650246f Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 27 Jan 2014 22:32:11 -0600 Subject: pbkdf2 docs --- docs/hazmat/primitives/index.rst | 1 + .../hazmat/primitives/key-derivation-functions.rst | 40 ++++++++++++++++++++++ 2 files changed, 41 insertions(+) create mode 100644 docs/hazmat/primitives/key-derivation-functions.rst (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index b115fdbc..2a29bd8f 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -9,6 +9,7 @@ Primitives cryptographic-hashes hmac symmetric-encryption + key-derivation-functions padding constant-time interfaces diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst new file mode 100644 index 00000000..af2d910f --- /dev/null +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -0,0 +1,40 @@ +.. hazmat:: + +Key Derivation Functions +======================== + +.. currentmodule:: cryptography.hazmat.primitives.kdf + +Key derivation functions derive key material from information such as passwords +using a pseudo-random function (PRF). + +.. class:: PBKDF2(algorithm, length, salt, iterations, backend): + + .. doctest:: + + >>> from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2 + >>> from cryptography.hazmat.backends import default_backend + >>> backend = default_backend() + >>> salt = os.urandom(16) + >>> # derive + >>> kdf = PBKDF2(hashes.SHA1(), 20, salt, 10000, backend) + >>> key = kdf.derive(b"my great password") + >>> # verify + >>> kdf = PBKDF2(hashes.SHA1(), 20, salt, 10000, backend) + >>> kdf.verify(b"my great password", key) + None + + :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 + 2\ :sup:`31` - 1. + + :param bytes salt: A salt. `NIST SP 800-132`_ recommends 128-bits or + longer. + + :param int iterations: The number of iterations to perform of the hash + function. + +.. _`NIST SP 800-132`: http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf -- cgit v1.2.3 From 5d1af21519c728f1514efc1018eb427e7fb18559 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 28 Jan 2014 12:19:32 -0600 Subject: documentation improvements for KDF --- docs/hazmat/primitives/index.rst | 2 +- .../hazmat/primitives/key-derivation-functions.rst | 31 +++++++++++++--------- 2 files changed, 20 insertions(+), 13 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 2a29bd8f..bde07392 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -9,7 +9,7 @@ Primitives cryptographic-hashes hmac symmetric-encryption - key-derivation-functions padding + key-derivation-functions constant-time interfaces diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index af2d910f..51d73bc2 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -10,8 +10,16 @@ using a pseudo-random function (PRF). .. class:: PBKDF2(algorithm, length, salt, iterations, backend): + .. versionadded:: 0.2 + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.KeyDerivationFunction` + interface. + .. doctest:: + >>> import os + >>> from cryptography.hazmat.primitives import hashes >>> from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2 >>> from cryptography.hazmat.backends import default_backend >>> backend = default_backend() @@ -22,19 +30,18 @@ using a pseudo-random function (PRF). >>> # verify >>> kdf = PBKDF2(hashes.SHA1(), 20, salt, 10000, backend) >>> kdf.verify(b"my great password", key) - None - - :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 + :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 2\ :sup:`31` - 1. - - :param bytes salt: A salt. `NIST SP 800-132`_ recommends 128-bits or - longer. - - :param int iterations: The number of iterations to perform of the hash - function. + :param bytes salt: A salt. `NIST SP 800-132`_ recommends 128-bits or + longer. + :param int iterations: The number of iterations to perform of the hash + function. + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` + provider. .. _`NIST SP 800-132`: http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf -- cgit v1.2.3 From 98e40e658ef00dc6972f5420896bd57b385c8435 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 28 Jan 2014 15:07:49 -0600 Subject: rename PBKDF2 to PBKDF2HMAC, address many other review comments --- 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 51d73bc2..bad7a36c 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -35,7 +35,7 @@ using a pseudo-random function (PRF). :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider. :param int length: The desired length of the derived key. Maximum is - 2\ :sup:`31` - 1. + (2\ :sup:`32` - 1) * ``algorithm.digest_size`` :param bytes salt: A salt. `NIST SP 800-132`_ recommends 128-bits or longer. :param int iterations: The number of iterations to perform of the hash -- cgit v1.2.3 From b3f763f1beae2a5fa1fdd3c27b6e9cb777ce7f50 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 28 Jan 2014 16:42:15 -0600 Subject: finish PBKDF2HMAC rename, more docs --- .../hazmat/primitives/key-derivation-functions.rst | 26 +++++++++++++++++----- 1 file changed, 20 insertions(+), 6 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 bad7a36c..661b4611 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -8,7 +8,7 @@ Key Derivation Functions Key derivation functions derive key material from information such as passwords using a pseudo-random function (PRF). -.. class:: PBKDF2(algorithm, length, salt, iterations, backend): +.. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend): .. versionadded:: 0.2 @@ -20,28 +20,42 @@ using a pseudo-random function (PRF). >>> import os >>> from cryptography.hazmat.primitives import hashes - >>> from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2 + >>> from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC >>> from cryptography.hazmat.backends import default_backend >>> backend = default_backend() >>> salt = os.urandom(16) >>> # derive - >>> kdf = PBKDF2(hashes.SHA1(), 20, salt, 10000, backend) + >>> kdf = PBKDF2HMAC( + ... algorithm=hashes.SHA256(), + ... length=32, + ... salt=salt, + ... iterations=50000, + ... backend=backend + ... ) >>> key = kdf.derive(b"my great password") >>> # verify - >>> kdf = PBKDF2(hashes.SHA1(), 20, salt, 10000, backend) + >>> kdf = PBKDF2HMAC( + ... algorithm=hashes.SHA256(), + ... length=32, + ... salt=salt, + ... iterations=50000, + ... backend=backend + ... ) >>> kdf.verify(b"my great password", 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 - (2\ :sup:`32` - 1) * ``algorithm.digest_size`` + (2\ :sup:`32` - 1) * ``algorithm.digest_size``. :param bytes salt: A salt. `NIST SP 800-132`_ recommends 128-bits or longer. :param int iterations: The number of iterations to perform of the hash - function. + function. See OWASP's `Password Storage Cheat Sheet`_ for more + detailed recommendations. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` provider. .. _`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 1277bc7e993dec8bbe64f1b5aeaaae6cff6429dd Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 28 Jan 2014 17:09:59 -0600 Subject: okay this time really finish the rename. Up example iterations to 100k --- 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 661b4611..4cb67701 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -29,7 +29,7 @@ using a pseudo-random function (PRF). ... algorithm=hashes.SHA256(), ... length=32, ... salt=salt, - ... iterations=50000, + ... iterations=100000, ... backend=backend ... ) >>> key = kdf.derive(b"my great password") @@ -38,7 +38,7 @@ using a pseudo-random function (PRF). ... algorithm=hashes.SHA256(), ... length=32, ... salt=salt, - ... iterations=50000, + ... iterations=100000, ... backend=backend ... ) >>> kdf.verify(b"my great password", key) -- cgit v1.2.3 From 3d8c66f9a01b8982902f69ae960fcc85aa43bfb8 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 28 Jan 2014 17:36:50 -0600 Subject: update docs with more detailed info re: PBKDF2 usage --- .../hazmat/primitives/key-derivation-functions.rst | 51 ++++++++++++++++++++-- 1 file changed, 48 insertions(+), 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 4cb67701..e16a9900 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -5,13 +5,21 @@ Key Derivation Functions .. currentmodule:: cryptography.hazmat.primitives.kdf -Key derivation functions derive key material from information such as passwords -using a pseudo-random function (PRF). +Key derivation functions derive key material from passwords or other data +sources using a pseudo-random function (PRF). Each KDF is suitable for +different tasks (cryptographic key derivation, password storage, +key stretching) so match your needs to their capabilities. .. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend): .. versionadded:: 0.2 + PBKDF2 (Password Based Key Derivation Function 2) is typically used for + deriving a cryptographic key from a password. It may also be used for + key storage, but other key storage KDFs such as `scrypt`_ or `bcrypt`_ + are generally considered better solutions since they are designed to be + slow. + This class conforms to the :class:`~cryptography.hazmat.primitives.interfaces.KeyDerivationFunction` interface. @@ -52,10 +60,47 @@ using a pseudo-random function (PRF). longer. :param int iterations: The number of iterations to perform of the hash function. See OWASP's `Password Storage Cheat Sheet`_ for more - detailed recommendations. + detailed recommendations if you intend to use this for password storage. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` provider. + .. method:: derive(key_material) + + :param key_material bytes: The input key material. For PBKDF2 this + should be a password. + :return: The new key. + :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 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 a user's password attempt 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 +.. _`bcrypt`: http://en.wikipedia.org/wiki/Bcrypt +.. _`scrypt`: http://en.wikipedia.org/wiki/Scrypt -- cgit v1.2.3 From 99d5190656184ad791e50eab72c631e7f829e283 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 28 Jan 2014 20:16:20 -0600 Subject: some alternate language --- 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 e16a9900..c77b763a 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -97,7 +97,7 @@ key stretching) so match your needs to their capabilities. 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 a user's password attempt matches the stored derived + 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 -- cgit v1.2.3 From 298e533e01053a5fc1ba00ba640a3daf128d1151 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 11:16:22 -0600 Subject: update docs for pbkdf2 --- docs/hazmat/primitives/key-derivation-functions.rst | 9 ++++----- 1 file changed, 4 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 c77b763a..e652ecbf 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -14,11 +14,10 @@ key stretching) so match your needs to their capabilities. .. versionadded:: 0.2 - PBKDF2 (Password Based Key Derivation Function 2) is typically used for + `PBKDF2`_ (Password Based Key Derivation Function 2) is typically used for deriving a cryptographic key from a password. It may also be used for - key storage, but other key storage KDFs such as `scrypt`_ or `bcrypt`_ - are generally considered better solutions since they are designed to be - slow. + key storage, but an alternate key storage KDF such as `scrypt` is generally + considered a better solution since it is designed to be slow. This class conforms to the :class:`~cryptography.hazmat.primitives.interfaces.KeyDerivationFunction` @@ -102,5 +101,5 @@ key stretching) so match your needs to their capabilities. .. _`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 -.. _`bcrypt`: http://en.wikipedia.org/wiki/Bcrypt +.. _`PBKDF2`: http://en.wikipedia.org/wiki/PBKDF2 .. _`scrypt`: http://en.wikipedia.org/wiki/Scrypt -- cgit v1.2.3 From e51a2db0def7b8f01b5a7ce96f35eb07b4d14599 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 11:49:35 -0600 Subject: document HashAlgorithm --- docs/hazmat/primitives/interfaces.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 2adad913..f31e9f4a 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -204,6 +204,34 @@ Asymmetric Interfaces The public exponent. Alias for :attr:`public_exponent`. +Hash Algorithms +~~~~~~~~~~~~~~~ + +.. class:: HashAlgorithm + + .. versionadded:: 0.2 + + .. attribute:: name + + :type: str + + The standard name for the hash algorithm, for example: ``sha1`` or + ``sha256``. + + .. attribute:: digest_size + + :type: int + + The size of the resulting digest in bytes. + + .. attribute:: block_size + + :type: int + + The internal block size of the hash algorithm in bytes. + + + Key Derivation Functions ~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 1d65a2fb2e559852e6e40b7230ca68094cb88571 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 11:50:45 -0600 Subject: fix spacing, remove versionadded since HashAlgorithm was in 0.1 --- docs/hazmat/primitives/interfaces.rst | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index f31e9f4a..cf7d5bfe 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -209,8 +209,6 @@ Hash Algorithms .. class:: HashAlgorithm - .. versionadded:: 0.2 - .. attribute:: name :type: str @@ -231,7 +229,6 @@ Hash Algorithms The internal block size of the hash algorithm in bytes. - Key Derivation Functions ~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 4c75a8c34610aef42e3bf3635a393d14a55273f8 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 12:20:37 -0600 Subject: quotes inside, diff examples --- 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 cf7d5bfe..09a5a4ce 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -213,8 +213,8 @@ Hash Algorithms :type: str - The standard name for the hash algorithm, for example: ``sha1`` or - ``sha256``. + The standard name for the hash algorithm, for example: ``"sha256"`` or + ``"whirlpool"``. .. attribute:: digest_size -- cgit v1.2.3 From c58b478530a93df90d0c612df259d1668cdd3f6b Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 13:56:25 -0600 Subject: update docs re: PBKDF2HMAC iterations --- docs/hazmat/primitives/key-derivation-functions.rst | 4 +++- 1 file changed, 3 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 e652ecbf..bf069faa 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -58,7 +58,9 @@ key stretching) so match your needs to their capabilities. :param bytes salt: A salt. `NIST SP 800-132`_ recommends 128-bits or longer. :param int iterations: The number of iterations to perform of the hash - function. See OWASP's `Password Storage Cheat Sheet`_ for more + function. This can be used to control the length of time the operation + takes. Higher numbers help mitigate brute force attacks against derived + keys. See OWASP's `Password Storage Cheat Sheet`_ for more detailed recommendations if you intend to use this for password storage. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` -- cgit v1.2.3 From 1cab104d7c95aae20bd6068c5cb54f4dce149d91 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 14:30:11 -0600 Subject: expand docs to talk more about the purposes of KDFs --- .../hazmat/primitives/key-derivation-functions.rst | 24 ++++++++++++++++++---- 1 file changed, 20 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 bf069faa..56c3a2bd 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -6,9 +6,24 @@ Key Derivation Functions .. currentmodule:: cryptography.hazmat.primitives.kdf Key derivation functions derive key material from passwords or other data -sources using a pseudo-random function (PRF). Each KDF is suitable for -different tasks (cryptographic key derivation, password storage, -key stretching) so match your needs to their capabilities. +sources using a pseudo-random function (PRF). Different KDFs are suitable for +different tasks such as: + +- Cryptographic key derivation + + 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.PBKDF2HMAC` or HKDF. + This process is typically known as `key stretching`_. + +- Password storage + + When storing passwords you want to use an algorithm that is computationally + intensive. Legitimate users will only need to compute it once (for example, + taking the user's password, running it through the KDF, then comparing it + to the stored value), while attackers will need to do it billions of times. + Ideal password storage KDFs will be demanding on both computational and + memory resources. .. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend): @@ -17,7 +32,7 @@ key stretching) so match your needs to their capabilities. `PBKDF2`_ (Password Based Key Derivation Function 2) is typically used for deriving a cryptographic key from a password. It may also be used for key storage, but an alternate key storage KDF such as `scrypt` is generally - considered a better solution since it is designed to be slow. + considered a better solution. This class conforms to the :class:`~cryptography.hazmat.primitives.interfaces.KeyDerivationFunction` @@ -105,3 +120,4 @@ key stretching) so match your needs to their capabilities. .. _`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 -- cgit v1.2.3 From 0b181182aef574c436a92a175937af32e54a2378 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 16:34:47 -0600 Subject: a bit more language work + changelog changes for pbkdf2hmac --- docs/hazmat/primitives/key-derivation-functions.rst | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 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 56c3a2bd..529f4416 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -5,18 +5,18 @@ Key Derivation Functions .. currentmodule:: cryptography.hazmat.primitives.kdf -Key derivation functions derive key material from passwords or other data -sources using a pseudo-random function (PRF). Different KDFs are suitable for -different tasks such as: +Key derivation functions derive bytes suitable for cryptographic operations +from passwords or other data sources using a pseudo-random function (PRF). +Different KDFs are suitable for different tasks such as: -- Cryptographic key derivation +* Cryptographic key derivation 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.PBKDF2HMAC` or HKDF. + such as :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC` or HKDF. This process is typically known as `key stretching`_. -- Password storage +* Password storage When storing passwords you want to use an algorithm that is computationally intensive. Legitimate users will only need to compute it once (for example, @@ -25,13 +25,15 @@ different tasks such as: Ideal password storage KDFs will be demanding on both computational and memory resources. -.. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend): +.. currentmodule:: cryptography.hazmat.primitives.kdf.pbkdf2 + +.. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend) .. versionadded:: 0.2 `PBKDF2`_ (Password Based Key Derivation Function 2) is typically used for deriving a cryptographic key from a password. It may also be used for - key storage, but an alternate key storage KDF such as `scrypt` is generally + key storage, but an alternate key storage KDF such as `scrypt`_ is generally considered a better solution. This class conforms to the @@ -85,7 +87,7 @@ different tasks such as: :param key_material bytes: The input key material. For PBKDF2 this should be a password. - :return: The new key. + :return bytes: the derived key. :raises cryptography.exceptions.AlreadyFinalized: This is raised when :meth:`derive` or :meth:`verify` is -- cgit v1.2.3 From 15a86a01dcbf3fc1209a7e44687aeb8c510b37b4 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 17:44:47 -0600 Subject: PBKDF2HMAC requires a PBKDF2HMACBackend provider. I cannot be trusted with a pasteboard --- 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 529f4416..551dbd6d 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -80,7 +80,7 @@ Different KDFs are suitable for different tasks such as: keys. See OWASP's `Password Storage Cheat Sheet`_ for more detailed recommendations if you intend to use this for password storage. :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` + :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend` provider. .. method:: derive(key_material) -- cgit v1.2.3