From 5df0abe1fe49c13d628a088c0caee2f6eed88a99 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 30 Oct 2013 16:57:04 -0500 Subject: add bf docs --- docs/hazmat/primitives/symmetric-encryption.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 1e047b7c..94d58eee 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -107,6 +107,15 @@ Ciphers ``56`` bits long), they can simply be concatenated to produce the full key. This must be kept secret. +.. 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 AES. + + :param bytes key: The secret key, 32-448 bits in length (in increments of + 8). This must be kept secret. + Modes ~~~~~ -- cgit v1.2.3 From 30b161375b168d7e32c27651f1906232b44909f8 Mon Sep 17 00:00:00 2001 From: David Reid Date: Thu, 31 Oct 2013 13:37:24 -0700 Subject: Update documentation --- docs/hazmat/primitives/cryptographic-hashes.rst | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index c780dcb0..9bbac247 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -5,7 +5,7 @@ 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. @@ -15,11 +15,11 @@ 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 +29,10 @@ 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. - .. method:: hexdigest() - - :return str: The message digest as hex. SHA-1 ~~~~~ -- cgit v1.2.3 From 3446d8103af433b0241b93850f2ff140eaf3cb11 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 31 Oct 2013 17:15:03 -0500 Subject: move blowfish docs to new weak ciphers section, linkify aes --- docs/hazmat/primitives/symmetric-encryption.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 94d58eee..31ceea8a 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -107,11 +107,21 @@ Ciphers ``56`` bits long), they can simply be concatenated to produce the full key. 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 AES. + 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. -- cgit v1.2.3 From 6022d455d722d56f29fabad81da68de63c2203ab Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 30 Oct 2013 17:03:54 -0500 Subject: add CAST5 docs --- docs/hazmat/primitives/symmetric-encryption.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 31ceea8a..5852dc21 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -107,6 +107,15 @@ 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 ------------ @@ -126,7 +135,6 @@ Weak Ciphers :param bytes key: The secret key, 32-448 bits in length (in increments of 8). This must be kept secret. - Modes ~~~~~ -- cgit v1.2.3 From 5560298b42f071db0bf7ea46c63ff52603370b38 Mon Sep 17 00:00:00 2001 From: David Reid Date: Fri, 1 Nov 2013 13:34:05 -0700 Subject: Improve Hash documentation. --- docs/hazmat/primitives/cryptographic-hashes.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 9bbac247..a939998d 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -7,10 +7,16 @@ Message Digests .. 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:: @@ -30,6 +36,9 @@ Message Digests :return: a new instance of this object with a copied internal state. .. method:: finalize() + Finalize the current context and return the message digest as bytes. + + Once ``finalize`` is called this object can no longer be used. :return bytes: The message digest as bytes. -- cgit v1.2.3 From 14968455bcc00af554a3371138f9ae530ff62afa Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 1 Nov 2013 14:05:14 -0700 Subject: fixed rendering --- docs/hazmat/primitives/cryptographic-hashes.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index a939998d..76ca20c0 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -36,6 +36,7 @@ Message Digests :return: a new instance of this object with a copied internal state. .. method:: finalize() + Finalize the current context and return the message digest as bytes. Once ``finalize`` is called this object can no longer be used. -- cgit v1.2.3 From 6753e39c1396dabb05e73ab7b24d9322eecbf976 Mon Sep 17 00:00:00 2001 From: David Reid Date: Fri, 1 Nov 2013 15:32:03 -0700 Subject: Update documentation --- docs/hazmat/primitives/hmac.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) (limited to 'docs') 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. -- cgit v1.2.3