From fcae15014dd9510969615a7f5100704955bbeb64 Mon Sep 17 00:00:00 2001 From: Alex Stapleton Date: Thu, 23 Jan 2014 20:43:34 +0000 Subject: Some docs --- docs/hazmat/bindings/openssl.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst index 373fe472..77623b22 100644 --- a/docs/hazmat/bindings/openssl.rst +++ b/docs/hazmat/bindings/openssl.rst @@ -22,6 +22,26 @@ These are `CFFI`_ bindings to the `OpenSSL`_ C library. This is a ``cffi`` library. It can be used to call OpenSSL functions, and access constants. + .. classmethod:: init_static_locks + + Enables the best available locking callback for OpenSSL. + See :ref:`openssl-threading`. + +.. _openssl-threading: + +Threading +--------- + +`cryptography` enables OpenSSLs `thread safety facilities`_ in two different +ways depending on the configuration of your system. Normally the locking +callbacks provided by your Python implementation specifically for OpenSSL will +be used. However if you have linked `cryptography` to a different version of +OpenSSL than that used by your Python implementation we enable an alternative +locking callback. This version is implemented in Python and so may result in +lower performance in some situations. In particular parallelism is reduced +because it has to acquire the GIL whenever any lock operations occur within +OpenSSL. .. _`CFFI`: https://cffi.readthedocs.org/ .. _`OpenSSL`: https://www.openssl.org/ +.. _`thread safety facilities`: http://www.openssl.org/docs/crypto/threads.html -- cgit v1.2.3 From 57e280b0f87096238b5cf5590e1157d433f6f049 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 10 Jan 2014 00:26:07 -0600 Subject: add doc info about how to link against homebrew OpenSSL on OS X --- docs/hazmat/backends/openssl.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index a1f2d28a..355a1ebb 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -40,4 +40,15 @@ You'll also need to generate your own ``openssl.ld`` file. For example:: You should replace the version string on the first line as appropriate for your build. +Using your own OpenSSL on OS X +------------------------------ + +To link cryptography against a custom version of OpenSSL you'll need to set +``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. + +An example using a `Homebrew`_ OpenSSL installation:: + + ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography + .. _`OpenSSL`: https://www.openssl.org/ +.. _`Homebrew`: http://brew.sh -- cgit v1.2.3 From 8caeb8ddde096686225f476146134e2ec65190b6 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 10 Jan 2014 12:38:14 -0600 Subject: add env so homebrew instructions work in fish as well as bash on OS X --- docs/hazmat/backends/openssl.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 355a1ebb..a2417cf2 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -48,7 +48,8 @@ To link cryptography against a custom version of OpenSSL you'll need to set An example using a `Homebrew`_ OpenSSL installation:: - ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography + env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography + .. _`OpenSSL`: https://www.openssl.org/ .. _`Homebrew`: http://brew.sh -- cgit v1.2.3 From 017f0b05ebe6026b0ad0d6205fca6ec1e60540b4 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 24 Jan 2014 10:20:36 -0600 Subject: add instructions on how to install openssl via homebrew --- docs/hazmat/backends/openssl.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index a2417cf2..d305520a 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -44,9 +44,12 @@ Using your own OpenSSL on OS X ------------------------------ To link cryptography against a custom version of OpenSSL you'll need to set -``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. +``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. OpenSSL can be installed via +`Homebrew`_:: -An example using a `Homebrew`_ OpenSSL installation:: + brew install openssl + +Then install cryptography linking against the brewed version:: env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography -- cgit v1.2.3 From 917e82e2da0091e90307b20cfa8feaf2fb211ada Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 24 Jan 2014 11:34:04 -0600 Subject: Mark that tehse are console sections so they syntax highlight --- docs/hazmat/backends/openssl.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index d305520a..926ec7d1 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -26,9 +26,11 @@ The options you need to add allow the linker to identify every symbol correctly even when multiple versions of the library are linked into the same program. If you are using your distribution's source packages these will probably be patched in for you already, otherwise you'll need to use options something like -this when configuring OpenSSL:: +this when configuring OpenSSL: - ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared +.. code-block:: console + + $ ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared You'll also need to generate your own ``openssl.ld`` file. For example:: @@ -45,13 +47,17 @@ Using your own OpenSSL on OS X To link cryptography against a custom version of OpenSSL you'll need to set ``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. OpenSSL can be installed via -`Homebrew`_:: +`Homebrew`_: + +.. code-block:: console + + $ brew install openssl - brew install openssl +Then install cryptography linking against the brewed version: -Then install cryptography linking against the brewed version:: +.. code-block:: console - env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography + $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography .. _`OpenSSL`: https://www.openssl.org/ -- cgit v1.2.3 From 5fb7eb442d56642f201ba016fa5e8f99943f0bfe Mon Sep 17 00:00:00 2001 From: Alex Stapleton Date: Fri, 24 Jan 2014 19:02:33 +0000 Subject: Backticks --- docs/hazmat/bindings/openssl.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst index 77623b22..557f8c4d 100644 --- a/docs/hazmat/bindings/openssl.rst +++ b/docs/hazmat/bindings/openssl.rst @@ -32,10 +32,10 @@ These are `CFFI`_ bindings to the `OpenSSL`_ C library. Threading --------- -`cryptography` enables OpenSSLs `thread safety facilities`_ in two different +``cryptography`` enables OpenSSLs `thread safety facilities`_ in two different ways depending on the configuration of your system. Normally the locking callbacks provided by your Python implementation specifically for OpenSSL will -be used. However if you have linked `cryptography` to a different version of +be used. However if you have linked ``cryptography`` to a different version of OpenSSL than that used by your Python implementation we enable an alternative locking callback. This version is implemented in Python and so may result in lower performance in some situations. In particular parallelism is reduced -- cgit v1.2.3 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') 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') 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') 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') 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') 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') 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') 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') 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') 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') 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') 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 1050ddf44f0713a587cd0ba239e23c95064a39bc Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 27 Jan 2014 21:04:03 -0600 Subject: PBKDF2 support for OpenSSL backend --- docs/hazmat/backends/interfaces.rst | 39 +++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 11e2f2a2..fa4f800c 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -131,3 +131,42 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: :class:`~cryptography.hazmat.primitives.interfaces.HashContext` + + + +.. class:: PBKDF2Backend + + A backend with methods for using PBKDF2. + + .. method:: pbkdf2_hash_supported(algorithm) + + Check if the specified ``algorithm`` is supported by this backend. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: ``True`` if the specified ``algorithm`` is supported for + PBKDF2 by this backend, otherwise ``False``. + + .. method:: derive_pbkdf2(self, algorithm, length, salt, iterations, + key_material) + + :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. `RFC 2898`_ recommends 64-bits or longer. + + :param int iterations: The number of iterations to perform of the hash + function. + + :param bytes key_material: The key material to use as a basis for + the derived key. This is typically a password. + + :return bytes: Derived key. + +.. _`RFC 2898`: https://www.ietf.org/rfc/rfc2898.txt -- 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/backends/interfaces.rst | 3 +- docs/hazmat/primitives/index.rst | 1 + .../hazmat/primitives/key-derivation-functions.rst | 40 ++++++++++++++++++++++ 3 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 docs/hazmat/primitives/key-derivation-functions.rst (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index fa4f800c..14ca6880 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -159,7 +159,7 @@ A specific ``backend`` may provide one or more of these interfaces. :param int length: The desired length of the derived key. Maximum is 2\ :sup:`31` - 1. - :param bytes salt: A salt. `RFC 2898`_ recommends 64-bits or longer. + :param bytes salt: A salt. :param int iterations: The number of iterations to perform of the hash function. @@ -169,4 +169,3 @@ A specific ``backend`` may provide one or more of these interfaces. :return bytes: Derived key. -.. _`RFC 2898`: https://www.ietf.org/rfc/rfc2898.txt 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/backends/interfaces.rst | 4 ++- docs/hazmat/primitives/index.rst | 2 +- .../hazmat/primitives/key-derivation-functions.rst | 31 +++++++++++++--------- 3 files changed, 23 insertions(+), 14 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 14ca6880..975a7b02 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -136,6 +136,8 @@ A specific ``backend`` may provide one or more of these interfaces. .. class:: PBKDF2Backend + .. versionadded:: 0.2 + A backend with methods for using PBKDF2. .. method:: pbkdf2_hash_supported(algorithm) @@ -157,7 +159,7 @@ A specific ``backend`` may provide one or more of these interfaces. provider. :param int length: The desired length of the derived key. Maximum is - 2\ :sup:`31` - 1. + 2\ :sup:`31` - 1. :param bytes salt: A salt. 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/backends/interfaces.rst | 16 ++++++++-------- docs/hazmat/primitives/key-derivation-functions.rst | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 975a7b02..e22c6bb3 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -134,32 +134,32 @@ A specific ``backend`` may provide one or more of these interfaces. -.. class:: PBKDF2Backend +.. class:: PBKDF2HMACBackend .. versionadded:: 0.2 - A backend with methods for using PBKDF2. + A backend with methods for using PBKDF2 using HMAC as a PRF. - .. method:: pbkdf2_hash_supported(algorithm) + .. method:: pbkdf2_hmac_supported(algorithm) Check if the specified ``algorithm`` is supported by this backend. - :param algorithm: An instance of a + :param prf: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider. :returns: ``True`` if the specified ``algorithm`` is supported for - PBKDF2 by this backend, otherwise ``False``. + PBKDF2 HMAC by this backend, otherwise ``False``. - .. method:: derive_pbkdf2(self, algorithm, length, salt, iterations, - key_material) + .. method:: derive_pbkdf2_hmac(self, algorithm, length, salt, iterations, + key_material) :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. + (2\ :sup:`32` - 1) * ``algorithm.digest_size`` :param bytes salt: A salt. 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') 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') 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') 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') 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 589b90826db025bcd7fc02e29b4831a09df3269d Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 28 Jan 2014 21:25:41 -0600 Subject: doc updates based on review --- docs/hazmat/backends/interfaces.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index e22c6bb3..ca3a5433 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -133,7 +133,6 @@ A specific ``backend`` may provide one or more of these interfaces. :class:`~cryptography.hazmat.primitives.interfaces.HashContext` - .. class:: PBKDF2HMACBackend .. versionadded:: 0.2 @@ -144,7 +143,7 @@ A specific ``backend`` may provide one or more of these interfaces. Check if the specified ``algorithm`` is supported by this backend. - :param prf: An instance of a + :param algorithm: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider. -- 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') 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 bc26efb3668a3f66fd13a6a8d3ef72f91e11af8e Mon Sep 17 00:00:00 2001 From: skeuomorf Date: Wed, 29 Jan 2014 08:31:47 +0200 Subject: Added canonical installation document with details about various platforms, fixes #519 --- docs/hazmat/backends/openssl.rst | 48 ---------------------------------------- 1 file changed, 48 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 926ec7d1..12d2d9f6 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -13,52 +13,4 @@ The `OpenSSL`_ C library. The string name of this backend: ``"openssl"`` -Using your own OpenSSL on Linux -------------------------------- - -Python links to OpenSSL for its own purposes and this can sometimes cause -problems when you wish to use a different version of OpenSSL with cryptography. -If you want to use cryptography with your own build of OpenSSL you will need to -make sure that the build is configured correctly so that your version of -OpenSSL doesn't conflict with Python's. - -The options you need to add allow the linker to identify every symbol correctly -even when multiple versions of the library are linked into the same program. If -you are using your distribution's source packages these will probably be -patched in for you already, otherwise you'll need to use options something like -this when configuring OpenSSL: - -.. code-block:: console - - $ ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared - -You'll also need to generate your own ``openssl.ld`` file. For example:: - - OPENSSL_1.0.1F_CUSTOM { - global: - *; - }; - -You should replace the version string on the first line as appropriate for your -build. - -Using your own OpenSSL on OS X ------------------------------- - -To link cryptography against a custom version of OpenSSL you'll need to set -``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. OpenSSL can be installed via -`Homebrew`_: - -.. code-block:: console - - $ brew install openssl - -Then install cryptography linking against the brewed version: - -.. code-block:: console - - $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography - - .. _`OpenSSL`: https://www.openssl.org/ -.. _`Homebrew`: http://brew.sh -- 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') 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') 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') 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/backends/interfaces.rst | 4 +++- docs/hazmat/primitives/key-derivation-functions.rst | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index ca3a5433..5b3e852a 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -163,7 +163,9 @@ A specific ``backend`` may provide one or more of these interfaces. :param bytes salt: A salt. :param int iterations: The number of iterations to perform of the hash - function. + function. This can be used to control the length of time the + operation takes. Higher numbers help mitigate brute force attacks + against derived keys. :param bytes key_material: The key material to use as a basis for the derived key. This is typically a password. 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') 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 446cc2ab9138811a464175767ef30bb110035ff4 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 14:39:30 -0600 Subject: a few typo fixes, capitalization, etc --- docs/hazmat/backends/interfaces.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 11e2f2a2..dc24f84d 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -37,7 +37,7 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: create_symmetric_encryption_ctx(cipher, mode) Create a - :class:`~cryptogrpahy.hazmat.primitives.interfaces.CipherContext` that + :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` that can be used for encrypting data with the symmetric ``cipher`` using the given ``mode``. @@ -56,7 +56,7 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: create_symmetric_decryption_ctx(cipher, mode) Create a - :class:`~cryptogrpahy.hazmat.primitives.interfaces.CipherContext` that + :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` that can be used for decrypting data with the symmetric ``cipher`` using the given ``mode``. @@ -91,7 +91,7 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: create_hash_ctx(algorithm) Create a - :class:`~cryptogrpahy.hazmat.primitives.interfaces.HashContext` that + :class:`~cryptography.hazmat.primitives.interfaces.HashContext` that uses the specified ``algorithm`` to calculate a message digest. :param algorithm: An instance of a @@ -121,7 +121,7 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: create_hmac_ctx(algorithm) Create a - :class:`~cryptogrpahy.hazmat.primitives.interfaces.HashContext` that + :class:`~cryptography.hazmat.primitives.interfaces.HashContext` that uses the specified ``algorithm`` to calculate a hash-based message authentication code. -- 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') 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') 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