diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/changelog.rst | 2 | ||||
| -rw-r--r-- | docs/contributing.rst | 3 | ||||
| -rw-r--r-- | docs/hazmat/backends/commoncrypto.rst | 11 | ||||
| -rw-r--r-- | docs/hazmat/backends/index.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/backends/multibackend.rst | 28 | ||||
| -rw-r--r-- | docs/hazmat/backends/openssl.rst | 9 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 12 | ||||
| -rw-r--r-- | docs/hazmat/primitives/key-derivation-functions.rst | 106 | ||||
| -rw-r--r-- | docs/index.rst | 4 | ||||
| -rw-r--r-- | docs/installation.rst | 7 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 1 |
11 files changed, 166 insertions, 18 deletions
diff --git a/docs/changelog.rst b/docs/changelog.rst index f401fe7c..e322b145 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -15,6 +15,8 @@ Changelog * Fixed compilation on systems where OpenSSL's ``ec.h`` header is not available, such as CentOS. * Added :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`. +* Added :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`. +* Added :doc:`/hazmat/backends/multibackend`. 0.1 - 2014-01-08 ~~~~~~~~~~~~~~~~ diff --git a/docs/contributing.rst b/docs/contributing.rst index 184ba214..74b854bd 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -41,7 +41,7 @@ follow the directions on the :doc:`security page </security>`. Code ---- -When in doubt, refer to `PEP 8`_ for Python code. +When in doubt, refer to :pep:`8` for Python code. Every code file must start with the boilerplate notice of the Apache License. Additionally, every Python code file must contain @@ -287,7 +287,6 @@ The HTML documentation index can now be found at .. _`GitHub`: https://github.com/pyca/cryptography .. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev -.. _`PEP 8`: http://www.peps.io/8/ .. _`syntax`: http://sphinx-doc.org/domains.html#info-field-lists .. _`pytest`: https://pypi.python.org/pypi/pytest .. _`tox`: https://pypi.python.org/pypi/tox diff --git a/docs/hazmat/backends/commoncrypto.rst b/docs/hazmat/backends/commoncrypto.rst index af2032b6..16a61337 100644 --- a/docs/hazmat/backends/commoncrypto.rst +++ b/docs/hazmat/backends/commoncrypto.rst @@ -11,7 +11,16 @@ The `CommonCrypto`_ C library provided by Apple on OS X and iOS. .. data:: cryptography.hazmat.backends.commoncrypto.backend - This is the exposed API for the CommonCrypto backend. It has one public attribute. + This is the exposed API for the CommonCrypto backend. + + It implements the following interfaces: + + * :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` + * :class:`~cryptography.hazmat.backends.interfaces.HashBackend` + * :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + * :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend` + + It has one additional public attribute. .. attribute:: name diff --git a/docs/hazmat/backends/index.rst b/docs/hazmat/backends/index.rst index dbc0724e..983a44e9 100644 --- a/docs/hazmat/backends/index.rst +++ b/docs/hazmat/backends/index.rst @@ -32,4 +32,5 @@ Individual Backends openssl commoncrypto + multibackend interfaces diff --git a/docs/hazmat/backends/multibackend.rst b/docs/hazmat/backends/multibackend.rst new file mode 100644 index 00000000..63177bef --- /dev/null +++ b/docs/hazmat/backends/multibackend.rst @@ -0,0 +1,28 @@ +.. hazmat:: + +MultiBackend +============ + +.. currentmodule:: cryptography.hazmat.backends.multibackend + +.. class:: MultiBackend(backends) + + .. versionadded:: 0.2 + + This class allows you to combine multiple backends into a single backend + which offers the combined features of all of its constituents. + + .. code-block:: pycon + + >>> from cryptography.hazmat.backends.multibackend import MultiBackend + >>> from cryptography.hazmat.primitives import hashes + >>> backend1.hash_supported(hashes.SHA256()) + False + >>> backend2.hash_supported(hashes.SHA1()) + True + >>> multi_backend = MultiBackend([backend1, backend2]) + >>> multi_backend.hash_supported(hashes.SHA1()) + True + + :param backends: A ``list`` of backend objects. Backends are checked for + feature support in the order they appear in this list. diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 1d40b93c..f7d6b710 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -9,6 +9,15 @@ The `OpenSSL`_ C library. This is the exposed API for the OpenSSL backend. + It implements the following interfaces: + + * :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` + * :class:`~cryptography.hazmat.backends.interfaces.HashBackend` + * :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + * :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend` + + It also exposes the following: + .. attribute:: name The string name of this backend: ``"openssl"`` diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 09a5a4ce..cbca5ed6 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -130,7 +130,13 @@ Asymmetric Interfaces The public exponent. - .. attribute:: key_length + .. attribute:: private_exponent + + :type: int + + The private exponent. + + .. attribute:: key_size :type: int @@ -152,7 +158,7 @@ Asymmetric Interfaces :type: int - The private exponent. + The private exponent. Alias for :attr:`private_exponent`. .. attribute:: n @@ -179,7 +185,7 @@ Asymmetric Interfaces The public modulus. - .. attribute:: key_length + .. attribute:: key_size :type: int diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 551dbd6d..1937c2ec 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -13,7 +13,8 @@ Different KDFs are suitable for different tasks such as: Deriving a key suitable for use as input to an encryption algorithm. Typically this means taking a password and running it through an algorithm - such as :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC` or HKDF. + such as :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC` or + :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`. This process is typically known as `key stretching`_. * Password storage @@ -85,7 +86,7 @@ Different KDFs are suitable for different tasks such as: .. method:: derive(key_material) - :param key_material bytes: The input key material. For PBKDF2 this + :param bytes key_material: The input key material. For PBKDF2 this should be a password. :return bytes: the derived key. :raises cryptography.exceptions.AlreadyFinalized: This is raised when @@ -98,9 +99,9 @@ Different KDFs are suitable for different tasks such as: .. method:: verify(key_material, expected_key) - :param key_material bytes: The input key material. This is the same as + :param bytes key_material: 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, + :param bytes expected_key: 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 @@ -118,8 +119,99 @@ Different KDFs are suitable for different tasks such as: checking whether the password a user provides matches the stored derived key. + +.. currentmodule:: cryptography.hazmat.primitives.kdf.hkdf + +.. class:: HKDF(algorithm, length, salt, info, backend) + + .. versionadded:: 0.2 + + `HKDF`_ (HMAC-based Extract-and-Expand Key Derivation Function) is suitable + for deriving keys of a fixed size used for other cryptographic operations. + + .. doctest:: + + >>> import os + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF + >>> from cryptography.hazmat.backends import default_backend + >>> backend = default_backend() + >>> salt = os.urandom(16) + >>> info = b"hkdf-example" + >>> hkdf = HKDF( + ... algorithm=hashes.SHA256(), + ... length=32, + ... salt=salt, + ... info=info, + ... backend=backend + ... ) + >>> key = hkdf.derive(b"input key") + >>> hkdf = HKDF( + ... algorithm=hashes.SHA256(), + ... length=32, + ... salt=salt, + ... info=info, + ... backend=backend + ... ) + >>> hkdf.verify(b"input key", 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 + ``255 * (algorithm.digest_size // 8)``. + + :param bytes salt: A salt. Randomizes the KDF's output. Optional, but + highly recommended. Ideally as many bits of entropy as the security + level of the hash: often that means cryptographically random and as + long as the hash output. Worse (shorter, less entropy) salt values can + still meaningfully contribute to security. May be reused. Does not have + to be secret, but may cause stronger security guarantees if secret; see + `RFC 5869`_ and the `HKDF paper`_ for more details. If ``None`` is + explicitly passed a default salt of ``algorithm.digest_size // 8`` null + bytes will be used. + + :param bytes info: Application specific context information. If ``None`` + is explicitly passed an empty byte string will be used. + + :params backend: A + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + provider. + + .. method:: derive(key_material) + + :param bytes key_material: The input key material. + :retunr bytes: The derived key. + + Derives a new key from the input key material by performing both the + extract and expand operations. + + .. 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. + .. _`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 -.. _`PBKDF2`: http://en.wikipedia.org/wiki/PBKDF2 -.. _`scrypt`: http://en.wikipedia.org/wiki/Scrypt -.. _`key stretching`: http://en.wikipedia.org/wiki/Key_stretching +.. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2 +.. _`scrypt`: https://en.wikipedia.org/wiki/Scrypt +.. _`key stretching`: https://en.wikipedia.org/wiki/Key_stretching +.. _`HKDF`: +.. _`RFC 5869`: https://tools.ietf.org/html/rfc5869 +.. _`HKDF paper`: https://eprint.iacr.org/2010/264 diff --git a/docs/index.rst b/docs/index.rst index 86cd42c6..49e99be4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,7 +28,9 @@ existing libraries: * Use of poor implementations of algorithms (i.e. ones with known side-channel attacks). * Lack of high level, "Cryptography for humans", APIs. -* Absence of algorithms such as AES-GCM. +* Absence of algorithms such as + :class:`AES-GCM <cryptography.hazmat.primitives.ciphers.modes.GCM>` and + :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`. * Poor introspectability, and thus poor testability. * Extremely error prone APIs, and bad defaults. diff --git a/docs/installation.rst b/docs/installation.rst index 2206107e..7e7348e2 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,5 +1,5 @@ -Installing -========== +Installation +============ You can install ``cryptography`` with ``pip``: @@ -7,10 +7,9 @@ You can install ``cryptography`` with ``pip``: $ pip install cryptography -Installation Notes -================== On Windows ---------- + 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 diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index e05efc6c..acb50ff6 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -17,6 +17,7 @@ invariants iOS pickleable plaintext +pseudorandom testability unencrypted unpadded |