diff options
Diffstat (limited to 'docs/hazmat')
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 15 | ||||
| -rw-r--r-- | docs/hazmat/backends/openssl.rst | 48 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 25 | ||||
| -rw-r--r-- | docs/hazmat/primitives/key-derivation-functions.rst | 43 |
4 files changed, 64 insertions, 67 deletions
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index e22c6bb3..49e4c88c 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. @@ -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. @@ -164,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/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/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 2adad913..09a5a4ce 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -204,6 +204,31 @@ Asymmetric Interfaces The public exponent. Alias for :attr:`public_exponent`. +Hash Algorithms +~~~~~~~~~~~~~~~ + +.. class:: HashAlgorithm + + .. attribute:: name + + :type: str + + The standard name for the hash algorithm, for example: ``"sha256"`` or + ``"whirlpool"``. + + .. 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 ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index c77b763a..529f4416 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -5,20 +5,36 @@ 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. +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: -.. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend): +* 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.pbkdf2.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. + +.. 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 + `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. This class conforms to the :class:`~cryptography.hazmat.primitives.interfaces.KeyDerivationFunction` @@ -59,7 +75,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` @@ -69,7 +87,7 @@ key stretching) so match your needs to their capabilities. :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 @@ -102,5 +120,6 @@ 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 +.. _`key stretching`: http://en.wikipedia.org/wiki/Key_stretching |