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/backends') 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/backends') 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/backends') 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/backends') 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 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/backends') 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 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/hazmat/backends') 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 -- 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 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/hazmat/backends') 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. -- 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 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/hazmat/backends') 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. -- 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/backends') 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 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/backends') 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 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 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/hazmat/backends') 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. -- 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/backends') 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