diff options
Diffstat (limited to 'docs/hazmat/primitives')
| -rw-r--r-- | docs/hazmat/primitives/cryptographic-hashes.rst | 29 | ||||
| -rw-r--r-- | docs/hazmat/primitives/hmac.rst | 23 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 18 |
3 files changed, 47 insertions, 23 deletions
diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index c780dcb0..76ca20c0 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -5,21 +5,27 @@ Message Digests .. currentmodule:: cryptography.hazmat.primitives.hashes -.. class:: BaseHash(data=None) +.. class:: Hash(algorithm) - Abstract base class that implements a common interface for all hash - algorithms that follow here. + A cryptographic hash function takes an arbitrary block of data and + calculates a fixed-size bit string (a digest), such that different data + results (with a high probability) in different digests. - If ``data`` is provided ``update(data)`` is called upon construction. + This is an implementation of + :class:`cryptography.hazmat.primitives.interfaces.HashContext` meant to + be used with + :class:`cryptography.hazmat.primitives.interfaces.HashAlgorithm` + implementations to provide an incremental interface to calculating + various message digests. .. doctest:: >>> from cryptography.hazmat.primitives import hashes - >>> digest = hashes.SHA256() + >>> digest = hashes.Hash(hashes.SHA256()) >>> digest.update(b"abc") >>> digest.update(b"123") - >>> digest.hexdigest() - '6ca13d52ca70c883e0f0bb101e425a89e8624de51db2d2392593af6a84118090' + >>> digest.finalize() + 'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90' .. method:: update(data) @@ -29,13 +35,14 @@ Message Digests :return: a new instance of this object with a copied internal state. - .. method:: digest() + .. method:: finalize() - :return bytes: The message digest as bytes. + Finalize the current context and return the message digest as bytes. + + Once ``finalize`` is called this object can no longer be used. - .. method:: hexdigest() + :return bytes: The message digest as bytes. - :return str: The message digest as hex. SHA-1 ~~~~~ diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 44cc29fa..bd1a4934 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -15,21 +15,23 @@ message authentication codes using a cryptographic hash function coupled with a secret key. You can use an HMAC to verify integrity as well as authenticate a message. -.. class:: HMAC(key, msg=None, digestmod=None) +.. class:: HMAC(key, algorithm) - HMAC objects take a ``key``, a hash class derived from - :class:`~cryptography.primitives.hashes.BaseHash`, and optional message. + HMAC objects take a ``key`` and a provider of + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`. The ``key`` should be randomly generated bytes and is recommended to be equal in length to the ``digest_size`` of the hash function chosen. You must keep the ``key`` secret. + This is an implementation of :rfc:`2104`. + .. doctest:: >>> from cryptography.hazmat.primitives import hashes, hmac - >>> h = hmac.HMAC(key, digestmod=hashes.SHA256) + >>> h = hmac.HMAC(key, hashes.SHA256()) >>> h.update(b"message to hash") - >>> h.hexdigest() - '...' + >>> h.finalize() + '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J' .. method:: update(msg) @@ -39,11 +41,10 @@ message. :return: a new instance of this object with a copied internal state. - .. method:: digest() - - :return bytes: The message digest as bytes. + .. method:: finalize() - .. method:: hexdigest() + Finalize the current context and return the message digest as bytes. - :return str: The message digest as hex. + Once ``finalize`` is called this object can no longer be used. + :return bytes: The message digest as bytes. diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 5852dc21..c1c8d247 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -42,12 +42,21 @@ where the encrypter and decrypter both use the same key. :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` provider. + If the backend doesn't support the requested combination of ``cipher`` + and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` + will be raised. + .. method:: decryptor() :return: A decrypting :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` provider. + If the backend doesn't support the requested combination of ``cipher`` + and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` + will be raised. + + .. currentmodule:: cryptography.hazmat.primitives.interfaces .. class:: CipherContext @@ -63,6 +72,12 @@ where the encrypter and decrypter both use the same key. :param bytes data: The data you wish to pass into the context. :return bytes: Returns the data that was encrypted or decrypted. + When the ``BlockCipher`` was constructed in a mode turns it into a + stream cipher (e.g. + :class:`cryptography.hazmat.primitives.block.modes.CTR`), this will + return bytes immediately, however in other modes it will return chunks, + whose size is determined by the cipher's block size. + .. method:: finalize() :return bytes: Returns the remainder of the data. @@ -162,7 +177,8 @@ Modes block size of less than 128-bits. CTR (Counter) is a mode of operation for block ciphers. It is considered - cryptographically strong. + cryptographically strong. It transforms a block cipher into a stream + cipher. :param bytes nonce: Should be random bytes. It is critical to never reuse a ``nonce`` with a given key. Any reuse of a nonce |