From 36e7d0df315dca887f5b073e17209ee3eeb5a576 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 18 Oct 2013 18:54:40 -0500 Subject: MD5 support + documentation for all hashes --- cryptography/primitives/hashes.py | 6 ++ docs/primitives/cryptographic-hashes.rst | 164 +++++++++++++++++++++++++++++++ docs/primitives/index.rst | 1 + tests/primitives/test_hash_vectors.py | 13 +++ tests/primitives/test_hashes.py | 10 ++ 5 files changed, 194 insertions(+) create mode 100644 docs/primitives/cryptographic-hashes.rst diff --git a/cryptography/primitives/hashes.py b/cryptography/primitives/hashes.py index 06d90a90..d0f4c226 100644 --- a/cryptography/primitives/hashes.py +++ b/cryptography/primitives/hashes.py @@ -82,3 +82,9 @@ class Whirlpool(BaseHash): name = "whirlpool" digest_size = 64 block_size = 64 + + +class MD5(BaseHash): + name = "md5" + digest_size = 16 + block_size = 64 diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst new file mode 100644 index 00000000..1499f762 --- /dev/null +++ b/docs/primitives/cryptographic-hashes.rst @@ -0,0 +1,164 @@ +Message Digests +==================== + +SHA-1 +~~~~~~~ + +.. attention:: + + NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications + are strongly suggested to use SHA-2 over SHA-1. + +.. class:: cryptography.primitives.hashes.SHA1() + + SHA-1 is a cryptographic hash function standardized by NIST. It has a + 160-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + + +SHA-2 Family +~~~~~~~ + +.. class:: cryptography.primitives.hashes.SHA224() + + SHA-224 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 224-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +.. class:: cryptography.primitives.hashes.SHA256() + + SHA-256 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 256-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +.. class:: cryptography.primitives.hashes.SHA384() + + SHA-384 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 384-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +.. class:: cryptography.primitives.hashes.SHA512() + + SHA-512 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 512-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +RIPEMD160 +~~~~~~~ + +.. class:: cryptography.primitives.hashes.RIPEMD160() + + RIPEMD160 is a cryptographic hash function that is part of ISO/IEC + 10118-3:2004. It has a 160-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +Whirlpool +~~~~~~~ + +.. class:: cryptography.primitives.hashes.Whirlpool() + + Whirlpool is a cryptographic hash function that is part of ISO/IEC + 10118-3:2004. It has a 512-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +MD5 +~~~~~~~ + +.. warning:: + + MD5 is a deprecated hash algorithm that has practical known collision + attacks. You are strongly discouraged from using it. + +.. class:: cryptography.primitives.hashes.MD5() + + MD5 is a deprecated cryptographic hash function. It has a 160-bit message + digest and has practical known collision attacks. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. diff --git a/docs/primitives/index.rst b/docs/primitives/index.rst index 1066e30e..c18c62ca 100644 --- a/docs/primitives/index.rst +++ b/docs/primitives/index.rst @@ -4,4 +4,5 @@ Primitives .. toctree:: :maxdepth: 1 + cryptographic-hashes symmetric-encryption diff --git a/tests/primitives/test_hash_vectors.py b/tests/primitives/test_hash_vectors.py index 52c972a3..02ef4dbb 100644 --- a/tests/primitives/test_hash_vectors.py +++ b/tests/primitives/test_hash_vectors.py @@ -131,3 +131,16 @@ class TestWhirlpool(object): only_if=lambda api: api.supports_hash(hashes.Whirlpool), skip_message="Does not support Whirlpool", ) + + +class TestMD5(object): + test_md5 = generate_hash_test( + load_hash_vectors_from_file, + os.path.join("RFC", "MD5"), + [ + "rfc-1321.txt", + ], + hashes.MD5, + only_if=lambda api: api.supports_hash(hashes.MD5), + skip_message="Does not support MD5", + ) diff --git a/tests/primitives/test_hashes.py b/tests/primitives/test_hashes.py index 982fc7cd..901ddabb 100644 --- a/tests/primitives/test_hashes.py +++ b/tests/primitives/test_hashes.py @@ -86,3 +86,13 @@ class TestWhirlpool(object): only_if=lambda api: api.supports_hash(hashes.Whirlpool), skip_message="Does not support Whirlpool", ) + + +class TestMD5(object): + test_MD5 = generate_base_hash_test( + hashes.MD5, + digest_size=16, + block_size=64, + only_if=lambda api: api.supports_hash(hashes.MD5), + skip_message="Does not support MD5", + ) -- cgit v1.2.3 From 9cd2ae4d4ca898cc4b9fee935d41422c70f9ccf1 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 19 Oct 2013 12:00:20 -0500 Subject: change basehash into an abc --- cryptography/primitives/hashes.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/cryptography/primitives/hashes.py b/cryptography/primitives/hashes.py index d0f4c226..a87d09e5 100644 --- a/cryptography/primitives/hashes.py +++ b/cryptography/primitives/hashes.py @@ -13,12 +13,16 @@ from __future__ import absolute_import, division, print_function +import abc + import binascii +import six + from cryptography.bindings import _default_api -class BaseHash(object): +class BaseHash(six.with_metaclass(abc.ABCMeta)): def __init__(self, api=None, ctx=None): if api is None: api = _default_api -- cgit v1.2.3 From 505491bd64dd410a3ac6c7f01c71e902a3c58917 Mon Sep 17 00:00:00 2001 From: Matthew Iversen Date: Sat, 19 Oct 2013 15:56:17 +1100 Subject: Simplify documentation --- docs/primitives/cryptographic-hashes.rst | 123 ++++++------------------------- 1 file changed, 24 insertions(+), 99 deletions(-) diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst index 1499f762..6e8f601b 100644 --- a/docs/primitives/cryptographic-hashes.rst +++ b/docs/primitives/cryptographic-hashes.rst @@ -1,23 +1,20 @@ Message Digests ==================== -SHA-1 -~~~~~~~ - -.. attention:: - - NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications - are strongly suggested to use SHA-2 over SHA-1. - -.. class:: cryptography.primitives.hashes.SHA1() +.. class:: cryptography.primitives.hashes.BaseHash - SHA-1 is a cryptographic hash function standardized by NIST. It has a - 160-bit message digest. + Abstract base class that implements a common interface for + all hash algorithms that follow here .. method:: update(string) :param bytes string: The bytes you wish to hash. + .. method:: copy() + + :return: a new instance of this object with a + copied internal state. + .. method:: digest() :return bytes: The message digest as bytes. @@ -26,120 +23,60 @@ SHA-1 :return str: The message digest as hex. +SHA-1 +~~~~~ -SHA-2 Family -~~~~~~~ - -.. class:: cryptography.primitives.hashes.SHA224() - - SHA-224 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 224-bit message digest. +.. attention:: - .. method:: update(string) + NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications + are strongly suggested to use SHA-2 over SHA-1. - :param bytes string: The bytes you wish to hash. +.. class:: cryptography.primitives.hashes.SHA1() - .. method:: digest() + SHA-1 is a cryptographic hash function standardized by NIST. It has a + 160-bit message digest. - :return bytes: The message digest as bytes. +SHA-2 Family +~~~~~~~~~~~~ - .. method:: hexdigest() +.. class:: cryptography.primitives.hashes.SHA224() - :return str: The message digest as hex. + SHA-224 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 224-bit message digest. .. class:: cryptography.primitives.hashes.SHA256() SHA-256 is a cryptographic hash function from the SHA-2 family and standardized by NIST. It has a 256-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - .. class:: cryptography.primitives.hashes.SHA384() SHA-384 is a cryptographic hash function from the SHA-2 family and standardized by NIST. It has a 384-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - .. class:: cryptography.primitives.hashes.SHA512() SHA-512 is a cryptographic hash function from the SHA-2 family and standardized by NIST. It has a 512-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - RIPEMD160 -~~~~~~~ +~~~~~~~~~ .. class:: cryptography.primitives.hashes.RIPEMD160() RIPEMD160 is a cryptographic hash function that is part of ISO/IEC 10118-3:2004. It has a 160-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - Whirlpool -~~~~~~~ +~~~~~~~~~ .. class:: cryptography.primitives.hashes.Whirlpool() Whirlpool is a cryptographic hash function that is part of ISO/IEC 10118-3:2004. It has a 512-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - MD5 -~~~~~~~ +~~~ .. warning:: @@ -150,15 +87,3 @@ MD5 MD5 is a deprecated cryptographic hash function. It has a 160-bit message digest and has practical known collision attacks. - - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. -- cgit v1.2.3 From 6b9ddeb015e3e36ba955c58191820ba1c07bdd76 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 19 Oct 2013 12:28:15 -0500 Subject: fix doc formatting and rename update param to "data" --- docs/primitives/cryptographic-hashes.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst index 6e8f601b..397e50d7 100644 --- a/docs/primitives/cryptographic-hashes.rst +++ b/docs/primitives/cryptographic-hashes.rst @@ -3,17 +3,16 @@ Message Digests .. class:: cryptography.primitives.hashes.BaseHash - Abstract base class that implements a common interface for - all hash algorithms that follow here + Abstract base class that implements a common interface for all hash + algorithms that follow here. - .. method:: update(string) + .. method:: update(data) - :param bytes string: The bytes you wish to hash. + :param bytes data The bytes you wish to hash. .. method:: copy() - :return: a new instance of this object with a - copied internal state. + :return: a new instance of this object with a copied internal state. .. method:: digest() -- cgit v1.2.3 From 746815b8f2b6a485b41e37c67969ed21338946db Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 19 Oct 2013 22:34:38 -0500 Subject: update method signature for hash update to be consistent with the docs --- cryptography/primitives/hashes.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cryptography/primitives/hashes.py b/cryptography/primitives/hashes.py index a87d09e5..e8c1f929 100644 --- a/cryptography/primitives/hashes.py +++ b/cryptography/primitives/hashes.py @@ -29,8 +29,8 @@ class BaseHash(six.with_metaclass(abc.ABCMeta)): self._api = api self._ctx = self._api.create_hash_context(self) if ctx is None else ctx - def update(self, string): - self._api.update_hash_context(self._ctx, string) + def update(self, data): + self._api.update_hash_context(self._ctx, data) def copy(self): return self.__class__(ctx=self._copy_ctx()) -- cgit v1.2.3