diff options
Diffstat (limited to 'docs/hazmat')
-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 |
6 files changed, 156 insertions, 11 deletions
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 |