diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/hazmat/primitives/cryptographic-hashes.rst | 29 | ||||
| -rw-r--r-- | docs/hazmat/primitives/hmac.rst | 21 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 27 |
3 files changed, 55 insertions, 22 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..301d72d5 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -15,10 +15,10 @@ 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. @@ -26,10 +26,10 @@ message. .. 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 +39,10 @@ message. :return: a new instance of this object with a copied internal state. - .. method:: digest() + .. method:: finalize() - :return bytes: The message digest as bytes. - - .. 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 1e047b7c..5852dc21 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -107,6 +107,33 @@ Ciphers ``56`` bits long), they can simply be concatenated to produce the full key. This must be kept secret. +.. class:: CAST5(key) + + CAST5 (also known as CAST-128) is a block cipher approved for use in the + Canadian government by their Communications Security Establishment. It is a + variable key length cipher and supports keys from 40-128 bits in length. + + :param bytes key: The secret key, 40-128 bits in length (in increments of + 8). This must be kept secret. + +Weak Ciphers +------------ + +.. warning:: + + These ciphers are considered weak for a variety of reasons. New + applications should avoid their use and existing applications should + strongly consider migrating away. + +.. class:: Blowfish(key) + + Blowfish is a block cipher developed by Bruce Schneier. It is known to be + susceptible to attacks when using weak keys. The author has recommended + that users of Blowfish move to newer algorithms like + :class:`AES`. + + :param bytes key: The secret key, 32-448 bits in length (in increments of + 8). This must be kept secret. Modes ~~~~~ |