From ed8d864f5412defe18d54dbf3c027120d4baeebe Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 19 Jan 2014 22:02:43 -0600 Subject: update changelog for commoncrypto backend --- docs/changelog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/changelog.rst b/docs/changelog.rst index 819b426a..c3859c25 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -6,7 +6,7 @@ Changelog **In development** -* Added :doc:`/hazmat/backends/commoncrypto` with hash and HMAC support. +* Added :doc:`/hazmat/backends/commoncrypto`. * Added initial :doc:`/hazmat/bindings/commoncrypto`. 0.1 - 2014-01-08 -- cgit v1.2.3 From 3c1eb12115e193285aaf790d095c300f5dcf7df1 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 23 Jan 2014 07:46:21 -0600 Subject: Capital S is the canonical URL --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 4bb1461d..3de41fd5 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -287,5 +287,5 @@ The HTML documentation index can now be found at .. _`tox`: https://pypi.python.org/pypi/tox .. _`virtualenv`: https://pypi.python.org/pypi/virtualenv .. _`pip`: https://pypi.python.org/pypi/pip -.. _`sphinx`: https://pypi.python.org/pypi/sphinx +.. _`sphinx`: https://pypi.python.org/pypi/Sphinx .. _`reStructured Text`: http://sphinx-doc.org/rest.html -- cgit v1.2.3 From a8fc6f32a5b9c8a5d055524a47c32ffa22530dcf Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 23 Jan 2014 10:48:16 -0600 Subject: Document where to get OpenSSL on windows --- docs/index.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index e17b4f9f..1100445f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,12 @@ You can install ``cryptography`` with ``pip``: $ 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. + + Why a new crypto library for Python? ------------------------------------ @@ -81,3 +87,6 @@ The ``cryptography`` open source project doing-a-release changelog community + + +.. _`pre-compiled binaries`: http://slproweb.com/products/Win32OpenSSL.html -- cgit v1.2.3 From e7651def41eb46053a7c5bc257ac146dc70b5025 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 23 Jan 2014 11:34:35 -0600 Subject: Link the official page --- 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 1100445f..a1cebc30 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -89,4 +89,4 @@ The ``cryptography`` open source project community -.. _`pre-compiled binaries`: http://slproweb.com/products/Win32OpenSSL.html +.. _`pre-compiled binaries`: https://www.openssl.org/related/binaries.html -- cgit v1.2.3 From b32b491a9d976165a1b8ca8565a272ce46fc2730 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 23 Jan 2014 16:24:13 -0600 Subject: DOcument the primitives used in Fernet --- docs/fernet.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'docs') diff --git a/docs/fernet.rst b/docs/fernet.rst index 13295c0c..b0215e32 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -72,5 +72,22 @@ symmetric (also known as "secret key") authenticated cryptography. See :meth:`Fernet.decrypt` for more information. +Implementation +-------------- + +Fernet is built on top of a number of standard cryptographic primitives. +Specifically it uses: + +* :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` in + :class:`~cryptography.hazmat.primitives.ciphers.modes.CBC` mode with a + 128-bit key for encryption; using + :class:`~cryptography.hazmat.primitives.ciphers.PKCS7` padding. +* :class:`~cryptography.hazmat.primitives.hmac.HMAC` using + :class:`~cryptography.hazmat.primitives.hashes.SHA256` for authentication. +* Initialization vectors are generated using ``os.urandom()``. + +For complete details consult the `specification`_. + .. _`Fernet`: https://github.com/fernet/spec/ +.. _`specification`: https://github.com/fernet/spec/blob/master/Spec.md -- cgit v1.2.3 From b495790a40a530c63b231fee9c5f21cae8a85648 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 23 Jan 2014 21:12:19 -0600 Subject: add windows support to changelog --- docs/changelog.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/changelog.rst b/docs/changelog.rst index 4b5a5be8..c8843821 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -10,6 +10,7 @@ Changelog * Added initial :doc:`/hazmat/bindings/commoncrypto`. * Removed ``register_cipher_adapter`` method from :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`. +* Added support for the OpenSSL backend under Windows. 0.1 - 2014-01-08 ~~~~~~~~~~~~~~~~ -- cgit v1.2.3 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') 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') 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') 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') 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') 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') 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 7ecb98503ddb1e580b6f8b1f33053d64b59bbba4 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 24 Jan 2014 15:17:47 -0600 Subject: Added thread safety to the changelog --- docs/changelog.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/changelog.rst b/docs/changelog.rst index c8843821..545d6945 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -11,6 +11,7 @@ Changelog * Removed ``register_cipher_adapter`` method from :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`. * Added support for the OpenSSL backend under Windows. +* Improved thread-safety for the OpenSSL backend. 0.1 - 2014-01-08 ~~~~~~~~~~~~~~~~ -- 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') 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') 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') 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') 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') 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') 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') 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/exceptions.rst | 6 ++++++ docs/hazmat/primitives/interfaces.rst | 30 ++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) (limited to 'docs') diff --git a/docs/exceptions.rst b/docs/exceptions.rst index 1fbd3267..f9e29f3c 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -30,3 +30,9 @@ Exceptions This is raised when a backend doesn't support the requested algorithm (or combination of algorithms). + + +.. class:: InvalidKey + + This is raised when the verify method of a key derivation function does not + compare equal. 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 288403a1a45554609d8b519d8b8d5a5abc9576c5 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 27 Jan 2014 15:59:17 -0800 Subject: Attempt some more natural language --- docs/exceptions.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/exceptions.rst b/docs/exceptions.rst index f9e29f3c..1e31e31c 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -10,8 +10,8 @@ Exceptions .. class:: InvalidSignature - This is raised when the verify method of a hash context does not - compare equal. + This is raised when the verify method of a hash context's computed digest + does not match the expected digest. .. class:: NotYetFinalized @@ -34,5 +34,5 @@ Exceptions .. class:: InvalidKey - This is raised when the verify method of a key derivation function does not - compare equal. + This is raised when the verify method of a key derivation function's + computed key does not match the expected key. -- cgit v1.2.3 From 24eb677117e79322fb07c2c807eef7bf2996828f Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 27 Jan 2014 16:15:54 -0800 Subject: DOcument that verify() apis should be provided --- docs/contributing.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 3de41fd5..f4bc769c 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -60,6 +60,12 @@ always indistinguishable. As a result ``cryptography`` has, as a design philosophy: "make it hard to do insecure things". Here are a few strategies for API design which should be both followed, and should inspire other API choices: +If a user will need to compare a user provided value with a computed value (for +example, checking a signature on something), there should be an API provided +which performs the check for the user in a secure way (for example, using a +constant time comparison), rather than requiring the user to perform the +comparison themselves. + If it is incorrect to ignore the result of a method, it should raise an exception, and not return a boolean ``True``/``False`` flag. For example, a method to verify a signature should raise ``InvalidSignature``, and not return -- cgit v1.2.3 From 61137bcd771f5e7e9f2f11625a75d15cb32b2816 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 27 Jan 2014 16:37:04 -0800 Subject: Reword for clarity --- docs/contributing.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index f4bc769c..184ba214 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -60,11 +60,11 @@ always indistinguishable. As a result ``cryptography`` has, as a design philosophy: "make it hard to do insecure things". Here are a few strategies for API design which should be both followed, and should inspire other API choices: -If a user will need to compare a user provided value with a computed value (for -example, checking a signature on something), there should be an API provided -which performs the check for the user in a secure way (for example, using a -constant time comparison), rather than requiring the user to perform the -comparison themselves. +If it is necessary to compare a user provided value with a computed value (for +example, verifying a signature), there should be an API provided which performs +the verification in a secure way (for example, using a constant time +comparison), rather than requiring the user to perform the comparison +themselves. If it is incorrect to ignore the result of a method, it should raise an exception, and not return a boolean ``True``/``False`` flag. For example, a -- cgit v1.2.3 From 7010df99d7096b8a0555752c51a1bd1e587c28dc Mon Sep 17 00:00:00 2001 From: Konstantinos Koukopoulos Date: Tue, 28 Jan 2014 03:35:25 -0800 Subject: document how to build w/ custom openssl on windows --- docs/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index a1cebc30..255c9e96 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,7 +17,8 @@ You can install ``cryptography`` with ``pip``: .. note:: If you're on Windows you'll need to make sure you have OpenSSL installed. - There are `pre-compiled binaries`_ available. + There are `pre-compiled binaries`_ available. If your installation is in + an unusual location ``set LIB=C:\OpenSSL-x.y.z\lib;%LIB%`` before installing. Why a new crypto library for Python? -- cgit v1.2.3 From 8f369b7cf68ae9018c04fea459d8b34587c3c6ed Mon Sep 17 00:00:00 2001 From: Konstantinos Koukopoulos Date: Tue, 28 Jan 2014 03:43:06 -0800 Subject: improve previous note on windows build --- docs/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 255c9e96..48ec0e45 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,7 +18,8 @@ You can install ``cryptography`` with ``pip``: 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 LIB=C:\OpenSSL-x.y.z\lib;%LIB%`` before installing. + an unusual location set the ``LIB`` and ``INCLUDE`` environment variables + to include the corresponding locations. Why a new crypto library for Python? -- 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') 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 5d9c6b207906c4ee084573b256b81a0c26da9b23 Mon Sep 17 00:00:00 2001 From: Konstantinos Koukopoulos Date: Tue, 28 Jan 2014 16:29:38 +0200 Subject: add example for windows installation --- docs/index.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 48ec0e45..b800bcaf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,7 +19,14 @@ You can install ``cryptography`` with ``pip``: 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. + 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? -- 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') 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') 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') 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') 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') 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') 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') 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') 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') 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 560ef47949077bbe89f108e1f3349cba4eacbbf0 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 28 Jan 2014 17:44:10 -0600 Subject: add PBKDF2HMAC to changelog --- docs/changelog.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/changelog.rst b/docs/changelog.rst index 545d6945..cc0aacd3 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -12,6 +12,7 @@ Changelog :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`. * Added support for the OpenSSL backend under Windows. * Improved thread-safety for the OpenSSL backend. +* Added PBKDF2HMAC support to OpenSSL backend. 0.1 - 2014-01-08 ~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 8a39c51dd5a8eb501411a7f90bb4001f96a99e20 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 28 Jan 2014 16:22:50 -0800 Subject: Add this to the changelog --- docs/changelog.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/changelog.rst b/docs/changelog.rst index 545d6945..5a8e9809 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -12,6 +12,8 @@ Changelog :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`. * Added support for the OpenSSL backend under Windows. * Improved thread-safety for the OpenSSL backend. +* Fixed compilation on systems where OpenSSL's ``ec.h`` header is not + available, such as CentOS. 0.1 - 2014-01-08 ~~~~~~~~~~~~~~~~ -- 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') 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') 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 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') 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