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') 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') 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 ------------------------- docs/index.rst | 31 ++++------------ docs/installation.rst | 76 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 83 insertions(+), 72 deletions(-) create mode 100644 docs/installation.rst (limited to 'docs') 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 diff --git a/docs/index.rst b/docs/index.rst index b800bcaf..73c40bf0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,30 +5,6 @@ Welcome to ``cryptography`` primitives. We hope it'll be your one-stop-shop for all your cryptographic needs in Python. -Installing ----------- - -You can install ``cryptography`` with ``pip``: - -.. code-block:: console - - $ pip install cryptography - -.. note:: - - If you're on Windows you'll need to make sure you have OpenSSL installed. - There are `pre-compiled binaries`_ available. If your installation is in - an unusual location set the ``LIB`` and ``INCLUDE`` environment variables - to include the corresponding locations. For example: - - .. code-block:: console - - C:\> \path\to\vcvarsall.bat x86_amd64 - C:\> set LIB=C:\OpenSSL-1.0.1f-64bit\lib;%LIB% - C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE% - C:\> pip install cryptography - - Why a new crypto library for Python? ------------------------------------ @@ -64,6 +40,13 @@ admonition at the top. We recommend using the recipes layer whenever possible, and falling back to the hazmat layer only when necessary. +Installation +~~~~~~~~~~~~ +.. toctree:: + :maxdepth: 2 + + installation + The recipes layer ~~~~~~~~~~~~~~~~~ diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 00000000..d9c30801 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,76 @@ +Installing +========== + +You can install ``cryptography`` with ``pip``: + +.. code-block:: console + + $ pip install cryptography + +Installation Notes +================== +On Windows +---------- +.. note:: + + If you're on Windows you'll need to make sure you have OpenSSL installed. + There are `pre-compiled binaries`_ available. If your installation is in + an unusual location set the ``LIB`` and ``INCLUDE`` environment variables + to include the corresponding locations. For example: + + .. code-block:: console + + C:\> \path\to\vcvarsall.bat x86_amd64 + C:\> set LIB=C:\OpenSSL-1.0.1f-64bit\lib;%LIB% + C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE% + C:\> pip install cryptography + +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 + + +.. _`Homebrew`: http://brew.sh +.. _`pre-compiled binaries`: https://www.openssl.org/related/binaries.html -- 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') 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') 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') 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 b0293bf7ed069fc1469d098cc71b9c50b9080d25 Mon Sep 17 00:00:00 2001 From: skeuomorf Date: Wed, 29 Jan 2014 21:41:02 +0200 Subject: Added installation section to index.rst --- docs/index.rst | 18 +++++++++++------- docs/installation.rst | 24 +++++++++++------------- 2 files changed, 22 insertions(+), 20 deletions(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 73c40bf0..93b25ecf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,6 +5,16 @@ Welcome to ``cryptography`` primitives. We hope it'll be your one-stop-shop for all your cryptographic needs in Python. +Installation +------------ +You can install ``cryptography`` with ``pip``: + +.. code-block:: console + + $ pip install cryptography + +see :doc:`Installation` for more information + Why a new crypto library for Python? ------------------------------------ @@ -40,13 +50,6 @@ admonition at the top. We recommend using the recipes layer whenever possible, and falling back to the hazmat layer only when necessary. -Installation -~~~~~~~~~~~~ -.. toctree:: - :maxdepth: 2 - - installation - The recipes layer ~~~~~~~~~~~~~~~~~ @@ -73,6 +76,7 @@ The ``cryptography`` open source project .. toctree:: :maxdepth: 2 + installation contributing security api-stability diff --git a/docs/installation.rst b/docs/installation.rst index d9c30801..2206107e 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -11,19 +11,17 @@ Installation Notes ================== On Windows ---------- -.. note:: - - If you're on Windows you'll need to make sure you have OpenSSL installed. - There are `pre-compiled binaries`_ available. If your installation is in - an unusual location set the ``LIB`` and ``INCLUDE`` environment variables - to include the corresponding locations. For example: - - .. code-block:: console - - C:\> \path\to\vcvarsall.bat x86_amd64 - C:\> set LIB=C:\OpenSSL-1.0.1f-64bit\lib;%LIB% - C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE% - C:\> pip install cryptography +If you're on Windows you'll need to make sure you have OpenSSL installed. +There are `pre-compiled binaries`_ available. If your installation is in +an unusual location set the ``LIB`` and ``INCLUDE`` environment variables +to include the corresponding locations. For example: + +.. code-block:: console + + C:\> \path\to\vcvarsall.bat x86_amd64 + C:\> set LIB=C:\OpenSSL-1.0.1f-64bit\lib;%LIB% + C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE% + C:\> pip install cryptography Using your own OpenSSL on Linux ------------------------------- -- 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') 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') 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 ++++---- docs/index.rst | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') 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. diff --git a/docs/index.rst b/docs/index.rst index 93b25ecf..d94e2fce 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,7 +13,7 @@ You can install ``cryptography`` with ``pip``: $ pip install cryptography -see :doc:`Installation` for more information +See :doc:`Installation` for more information. Why a new crypto library for Python? ------------------------------------ -- cgit v1.2.3 From f3b57e38ed3fd70dcb188a9eb6b84cf7cee01f85 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 14:45:10 -0600 Subject: one more style fix --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index d94e2fce..86cd42c6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,7 +13,7 @@ You can install ``cryptography`` with ``pip``: $ pip install cryptography -See :doc:`Installation` for more information. +See :doc:`Installation ` for more information. Why a new crypto library for Python? ------------------------------------ -- 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/changelog.rst | 2 +- docs/hazmat/primitives/key-derivation-functions.rst | 20 +++++++++++--------- 2 files changed, 12 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/changelog.rst b/docs/changelog.rst index be42b5db..f401fe7c 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -14,7 +14,7 @@ Changelog * Improved thread-safety for the OpenSSL backend. * Fixed compilation on systems where OpenSSL's ``ec.h`` header is not available, such as CentOS. -* Added PBKDF2HMAC support to OpenSSL backend. +* Added :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`. 0.1 - 2014-01-08 ~~~~~~~~~~~~~~~~ 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