diff --git a/Lib/hmac.py b/Lib/hmac.py index 8b4eb2fe74..16022c9ceb 100644 --- a/Lib/hmac.py +++ b/Lib/hmac.py @@ -3,7 +3,6 @@ Implements the HMAC algorithm as described by RFC 2104. """ -import warnings as _warnings try: import _hashlib as _hashopenssl except ImportError: @@ -14,7 +13,10 @@ compare_digest = _hashopenssl.compare_digest _functype = type(_hashopenssl.openssl_sha256) # builtin type -import hashlib as _hashlib +try: + import _hmac +except ImportError: + _hmac = None trans_5C = bytes((x ^ 0x5C) for x in range(256)) trans_36 = bytes((x ^ 0x36) for x in range(256)) @@ -24,11 +26,27 @@ digest_size = None +def _get_digest_constructor(digest_like): + if callable(digest_like): + return digest_like + if isinstance(digest_like, str): + def digest_wrapper(d=b''): + import hashlib + return hashlib.new(digest_like, d) + else: + def digest_wrapper(d=b''): + return digest_like.new(d) + return digest_wrapper + + class HMAC: """RFC 2104 HMAC class. Also complies with RFC 4231. This supports the API for Cryptographic Hash Functions (PEP 247). """ + + # Note: self.blocksize is the default blocksize; self.block_size + # is effective block size as well as the public API attribute. blocksize = 64 # 512-bit HMAC; can be changed in subclasses. __slots__ = ( @@ -50,31 +68,47 @@ def __init__(self, key, msg=None, digestmod=''): """ if not isinstance(key, (bytes, bytearray)): - raise TypeError("key: expected bytes or bytearray, but got %r" % type(key).__name__) + raise TypeError(f"key: expected bytes or bytearray, " + f"but got {type(key).__name__!r}") if not digestmod: raise TypeError("Missing required argument 'digestmod'.") + self.__init(key, msg, digestmod) + + def __init(self, key, msg, digestmod): if _hashopenssl and isinstance(digestmod, (str, _functype)): try: - self._init_hmac(key, msg, digestmod) - except _hashopenssl.UnsupportedDigestmodError: - self._init_old(key, msg, digestmod) - else: - self._init_old(key, msg, digestmod) + self._init_openssl_hmac(key, msg, digestmod) + return + except _hashopenssl.UnsupportedDigestmodError: # pragma: no cover + pass + if _hmac and isinstance(digestmod, str): + try: + self._init_builtin_hmac(key, msg, digestmod) + return + except _hmac.UnknownHashError: # pragma: no cover + pass + self._init_old(key, msg, digestmod) - def _init_hmac(self, key, msg, digestmod): + def _init_openssl_hmac(self, key, msg, digestmod): self._hmac = _hashopenssl.hmac_new(key, msg, digestmod=digestmod) + self._inner = self._outer = None # because the slots are defined + self.digest_size = self._hmac.digest_size + self.block_size = self._hmac.block_size + + _init_hmac = _init_openssl_hmac # for backward compatibility (if any) + + def _init_builtin_hmac(self, key, msg, digestmod): + self._hmac = _hmac.new(key, msg, digestmod=digestmod) + self._inner = self._outer = None # because the slots are defined self.digest_size = self._hmac.digest_size self.block_size = self._hmac.block_size def _init_old(self, key, msg, digestmod): - if callable(digestmod): - digest_cons = digestmod - elif isinstance(digestmod, str): - digest_cons = lambda d=b'': _hashlib.new(digestmod, d) - else: - digest_cons = lambda d=b'': digestmod.new(d) + import warnings + + digest_cons = _get_digest_constructor(digestmod) self._hmac = None self._outer = digest_cons() @@ -84,21 +118,19 @@ def _init_old(self, key, msg, digestmod): if hasattr(self._inner, 'block_size'): blocksize = self._inner.block_size if blocksize < 16: - _warnings.warn('block_size of %d seems too small; using our ' - 'default of %d.' % (blocksize, self.blocksize), - RuntimeWarning, 2) - blocksize = self.blocksize + warnings.warn(f"block_size of {blocksize} seems too small; " + f"using our default of {self.blocksize}.", + RuntimeWarning, 2) + blocksize = self.blocksize # pragma: no cover else: - _warnings.warn('No block_size attribute on given digest object; ' - 'Assuming %d.' % (self.blocksize), - RuntimeWarning, 2) - blocksize = self.blocksize + warnings.warn("No block_size attribute on given digest object; " + f"Assuming {self.blocksize}.", + RuntimeWarning, 2) + blocksize = self.blocksize # pragma: no cover if len(key) > blocksize: key = digest_cons(key).digest() - # self.blocksize is the default blocksize. self.block_size is - # effective block size as well as the public API attribute. self.block_size = blocksize key = key.ljust(blocksize, b'\0') @@ -164,6 +196,7 @@ def hexdigest(self): h = self._current() return h.hexdigest() + def new(key, msg=None, digestmod=''): """Create a new hashing object and return it. @@ -193,25 +226,41 @@ def digest(key, msg, digest): A hashlib constructor returning a new hash object. *OR* A module supporting PEP 247. """ - if _hashopenssl is not None and isinstance(digest, (str, _functype)): + if _hashopenssl and isinstance(digest, (str, _functype)): try: return _hashopenssl.hmac_digest(key, msg, digest) + except OverflowError: + # OpenSSL's HMAC limits the size of the key to INT_MAX. + # Instead of falling back to HACL* implementation which + # may still not be supported due to a too large key, we + # directly switch to the pure Python fallback instead + # even if we could have used streaming HMAC for small keys + # but large messages. + return _compute_digest_fallback(key, msg, digest) except _hashopenssl.UnsupportedDigestmodError: pass - if callable(digest): - digest_cons = digest - elif isinstance(digest, str): - digest_cons = lambda d=b'': _hashlib.new(digest, d) - else: - digest_cons = lambda d=b'': digest.new(d) + if _hmac and isinstance(digest, str): + try: + return _hmac.compute_digest(key, msg, digest) + except (OverflowError, _hmac.UnknownHashError): + # HACL* HMAC limits the size of the key to UINT32_MAX + # so we fallback to the pure Python implementation even + # if streaming HMAC may have been used for small keys + # and large messages. + pass + + return _compute_digest_fallback(key, msg, digest) + +def _compute_digest_fallback(key, msg, digest): + digest_cons = _get_digest_constructor(digest) inner = digest_cons() outer = digest_cons() blocksize = getattr(inner, 'block_size', 64) if len(key) > blocksize: key = digest_cons(key).digest() - key = key + b'\x00' * (blocksize - len(key)) + key = key.ljust(blocksize, b'\0') inner.update(key.translate(trans_36)) outer.update(key.translate(trans_5C)) inner.update(msg) diff --git a/Lib/test/test_hmac.py b/Lib/test/test_hmac.py index 1726975e86..30cb02b671 100644 --- a/Lib/test/test_hmac.py +++ b/Lib/test/test_hmac.py @@ -1,149 +1,429 @@ +"""Test suite for HMAC. + +Python provides three different implementations of HMAC: + +- OpenSSL HMAC using OpenSSL hash functions. +- HACL* HMAC using HACL* hash functions. +- Generic Python HMAC using user-defined hash functions. + +The generic Python HMAC implementation is able to use OpenSSL +callables or names, HACL* named hash functions or arbitrary +objects implementing PEP 247 interface. + +In the two first cases, Python HMAC wraps a C HMAC object (either OpenSSL +or HACL*-based). As a last resort, HMAC is re-implemented in pure Python. +It is however interesting to test the pure Python implementation against +the OpenSSL and HACL* hash functions. +""" + import binascii import functools import hmac import hashlib +import random +import types import unittest -import unittest.mock import warnings - -from test.support import hashlib_helper, check_disallow_instantiation - from _operator import _compare_digest as operator_compare_digest +from test.support import _4G, bigmemtest +from test.support import check_disallow_instantiation +from test.support import hashlib_helper, import_helper +from test.support.hashlib_helper import ( + BuiltinHashFunctionsTrait, + HashFunctionsTrait, + NamedHashFunctionsTrait, + OpenSSLHashFunctionsTrait, +) +from test.support.import_helper import import_fresh_module +from unittest.mock import patch try: - import _hashlib as _hashopenssl - from _hashlib import HMAC as C_HMAC - from _hashlib import hmac_new as c_hmac_new + import _hashlib from _hashlib import compare_digest as openssl_compare_digest except ImportError: - _hashopenssl = None - C_HMAC = None - c_hmac_new = None + _hashlib = None openssl_compare_digest = None try: - import _sha256 as sha256_module + import _sha2 as sha2 except ImportError: - sha256_module = None + sha2 = None -def ignore_warning(func): - @functools.wraps(func) - def wrapper(*args, **kwargs): - with warnings.catch_warnings(): - warnings.filterwarnings("ignore", - category=DeprecationWarning) - return func(*args, **kwargs) - return wrapper +def requires_builtin_sha2(): + return unittest.skipIf(sha2 is None, "requires _sha2") -class TestVectorsTestCase(unittest.TestCase): +class ModuleMixin: + """Mixin with a HMAC module implementation.""" - # TODO: RUSTPYTHON - @unittest.expectedFailure - def assert_hmac_internals( - self, h, digest, hashname, digest_size, block_size - ): - self.assertEqual(h.hexdigest().upper(), digest.upper()) - self.assertEqual(h.digest(), binascii.unhexlify(digest)) + hmac = None + + +class PyModuleMixin(ModuleMixin): + """Pure Python implementation of HMAC. + + The underlying hash functions may be OpenSSL-based or HACL* based, + depending on whether OpenSSL is present or not. + """ + + @classmethod + def setUpClass(cls): + super().setUpClass() + cls.hmac = import_fresh_module('hmac', blocked=['_hashlib', '_hmac']) + + +@hashlib_helper.requires_builtin_hmac() +class BuiltinModuleMixin(ModuleMixin): + """Built-in HACL* implementation of HMAC.""" + + @classmethod + def setUpClass(cls): + super().setUpClass() + cls.hmac = import_fresh_module('_hmac') + + +# Sentinel object used to detect whether a digestmod is given or not. +DIGESTMOD_SENTINEL = object() + + +class CreatorMixin: + """Mixin exposing a method creating a HMAC object.""" + + def hmac_new(self, key, msg=None, digestmod=DIGESTMOD_SENTINEL): + """Create a new HMAC object. + + Implementations should accept arbitrary 'digestmod' as this + method can be used to test which exceptions are being raised. + """ + raise NotImplementedError + + def bind_hmac_new(self, digestmod): + """Return a specialization of hmac_new() with a bound digestmod.""" + return functools.partial(self.hmac_new, digestmod=digestmod) + + +class DigestMixin: + """Mixin exposing a method computing a HMAC digest.""" + + def hmac_digest(self, key, msg=None, digestmod=DIGESTMOD_SENTINEL): + """Compute a HMAC digest. + + Implementations should accept arbitrary 'digestmod' as this + method can be used to test which exceptions are being raised. + """ + raise NotImplementedError + + def bind_hmac_digest(self, digestmod): + """Return a specialization of hmac_digest() with a bound digestmod.""" + return functools.partial(self.hmac_digest, digestmod=digestmod) + + +def _call_newobj_func(new_func, key, msg, digestmod): + if digestmod is DIGESTMOD_SENTINEL: # to test when digestmod is missing + return new_func(key, msg) # expected to raise + # functions creating HMAC objects take a 'digestmod' keyword argument + return new_func(key, msg, digestmod=digestmod) + + +def _call_digest_func(digest_func, key, msg, digestmod): + if digestmod is DIGESTMOD_SENTINEL: # to test when digestmod is missing + return digest_func(key, msg) # expected to raise + # functions directly computing digests take a 'digest' keyword argument + return digest_func(key, msg, digest=digestmod) + + +class ThroughObjectMixin(ModuleMixin, CreatorMixin, DigestMixin): + """Mixin delegating to .HMAC() and .HMAC(...).digest(). + + Both the C implementation and the Python implementation of HMAC should + expose a HMAC class with the same functionalities. + """ + + def hmac_new(self, key, msg=None, digestmod=DIGESTMOD_SENTINEL): + """Create a HMAC object via a module-level class constructor.""" + return _call_newobj_func(self.hmac.HMAC, key, msg, digestmod) + + def hmac_digest(self, key, msg=None, digestmod=DIGESTMOD_SENTINEL): + """Call the digest() method on a HMAC object obtained by hmac_new().""" + return _call_newobj_func(self.hmac_new, key, msg, digestmod).digest() + + +class ThroughModuleAPIMixin(ModuleMixin, CreatorMixin, DigestMixin): + """Mixin delegating to .new() and .digest().""" + + def hmac_new(self, key, msg=None, digestmod=DIGESTMOD_SENTINEL): + """Create a HMAC object via a module-level function.""" + return _call_newobj_func(self.hmac.new, key, msg, digestmod) + + def hmac_digest(self, key, msg=None, digestmod=DIGESTMOD_SENTINEL): + """One-shot HMAC digest computation.""" + return _call_digest_func(self.hmac.digest, key, msg, digestmod) + + +@hashlib_helper.requires_hashlib() +class ThroughOpenSSLAPIMixin(CreatorMixin, DigestMixin): + """Mixin delegating to _hashlib.hmac_new() and _hashlib.hmac_digest().""" + + def hmac_new(self, key, msg=None, digestmod=DIGESTMOD_SENTINEL): + return _call_newobj_func(_hashlib.hmac_new, key, msg, digestmod) + + def hmac_digest(self, key, msg=None, digestmod=DIGESTMOD_SENTINEL): + return _call_digest_func(_hashlib.hmac_digest, key, msg, digestmod) + + +class ThroughBuiltinAPIMixin(BuiltinModuleMixin, CreatorMixin, DigestMixin): + """Mixin delegating to _hmac.new() and _hmac.compute_digest().""" + + def hmac_new(self, key, msg=None, digestmod=DIGESTMOD_SENTINEL): + return _call_newobj_func(self.hmac.new, key, msg, digestmod) + + def hmac_digest(self, key, msg=None, digestmod=DIGESTMOD_SENTINEL): + return _call_digest_func(self.hmac.compute_digest, key, msg, digestmod) + + +class ObjectCheckerMixin: + """Mixin for checking HMAC objects (pure Python, OpenSSL or built-in).""" + + def check_object(self, h, hexdigest, hashname, digest_size, block_size): + """Check a HMAC object 'h' against the given values.""" + self.check_internals(h, hashname, digest_size, block_size) + self.check_hexdigest(h, hexdigest, digest_size) + + def check_internals(self, h, hashname, digest_size, block_size): + """Check the constant attributes of a HMAC object.""" self.assertEqual(h.name, f"hmac-{hashname}") self.assertEqual(h.digest_size, digest_size) self.assertEqual(h.block_size, block_size) - # TODO: RUSTPYTHON - @unittest.expectedFailure + def check_hexdigest(self, h, hexdigest, digest_size): + """Check the HMAC digest of 'h' and its size.""" + self.assertEqual(len(h.digest()), digest_size) + self.assertEqual(h.digest(), binascii.unhexlify(hexdigest)) + self.assertEqual(h.hexdigest().upper(), hexdigest.upper()) + + +class AssertersMixin(CreatorMixin, DigestMixin, ObjectCheckerMixin): + """Mixin class for common tests.""" + + def hmac_new_by_name(self, key, msg=None, *, hashname): + """Alternative implementation of hmac_new(). + + This is typically useful when one needs to test against an HMAC + implementation which only recognizes underlying hash functions + by their name (all HMAC implementations must at least recognize + hash functions by their names but some may use aliases such as + `hashlib.sha1` instead of "sha1"). + + Unlike hmac_new(), this method may assert the type of 'hashname' + as it should only be used in tests that are expected to create + a HMAC object. + """ + self.assertIsInstance(hashname, str) + return self.hmac_new(key, msg, digestmod=hashname) + + def hmac_digest_by_name(self, key, msg=None, *, hashname): + """Alternative implementation of hmac_digest(). + + Unlike hmac_digest(), this method may assert the type of 'hashname' + as it should only be used in tests that are expected to compute a + HMAC digest. + """ + self.assertIsInstance(hashname, str) + return self.hmac_digest(key, msg, digestmod=hashname) + def assert_hmac( - self, key, data, digest, hashfunc, hashname, digest_size, block_size + self, key, msg, hexdigest, hashfunc, hashname, digest_size, block_size ): - h = hmac.HMAC(key, data, digestmod=hashfunc) - self.assert_hmac_internals( - h, digest, hashname, digest_size, block_size + """Check that HMAC(key, msg) == digest. + + The 'hashfunc' and 'hashname' are used as 'digestmod' values, + thereby allowing to test the underlying dispatching mechanism. + + Note that 'hashfunc' may be a string, a callable, or a PEP-257 + module. Note that not all HMAC implementations may recognize the + same set of types for 'hashfunc', but they should always accept + a hash function by its name. + """ + if hashfunc == hashname: + choices = [hashname] + else: + choices = [hashfunc, hashname] + + for digestmod in choices: + with self.subTest(digestmod=digestmod): + self.assert_hmac_new( + key, msg, hexdigest, digestmod, + hashname, digest_size, block_size + ) + self.assert_hmac_hexdigest( + key, msg, hexdigest, digestmod, digest_size + ) + self.assert_hmac_common_cases( + key, msg, hexdigest, digestmod, + hashname, digest_size, block_size + ) + self.assert_hmac_extra_cases( + key, msg, hexdigest, digestmod, + hashname, digest_size, block_size + ) + + self.assert_hmac_new_by_name( + key, msg, hexdigest, hashname, digest_size, block_size + ) + self.assert_hmac_hexdigest_by_name( + key, msg, hexdigest, hashname, digest_size + ) + + def assert_hmac_new( + self, key, msg, hexdigest, digestmod, hashname, digest_size, block_size + ): + """Check that HMAC(key, msg) == digest. + + This test uses the `hmac_new()` method to create HMAC objects. + """ + self.check_hmac_new( + key, msg, hexdigest, hashname, digest_size, block_size, + hmac_new_func=self.hmac_new, + hmac_new_kwds={'digestmod': digestmod}, ) - h = hmac.HMAC(key, data, digestmod=hashname) - self.assert_hmac_internals( - h, digest, hashname, digest_size, block_size + def assert_hmac_new_by_name( + self, key, msg, hexdigest, hashname, digest_size, block_size + ): + """Check that HMAC(key, msg) == digest. + + This test uses the `hmac_new_by_name()` method to create HMAC objects. + """ + self.check_hmac_new( + key, msg, hexdigest, hashname, digest_size, block_size, + hmac_new_func=self.hmac_new_by_name, + hmac_new_kwds={'hashname': hashname}, ) - h = hmac.HMAC(key, digestmod=hashname) - h2 = h.copy() - h2.update(b"test update") - h.update(data) - self.assertEqual(h.hexdigest().upper(), digest.upper()) + def check_hmac_new( + self, key, msg, hexdigest, hashname, digest_size, block_size, + hmac_new_func, hmac_new_kwds=types.MappingProxyType({}), + ): + """Check that HMAC(key, msg) == digest. + + This also tests that using an empty/None initial message and + then calling `h.update(msg)` produces the same result, namely + that HMAC(key, msg) is equivalent to HMAC(key).update(msg). + """ + h = hmac_new_func(key, msg, **hmac_new_kwds) + self.check_object(h, hexdigest, hashname, digest_size, block_size) + + def hmac_new_feed(*args): + h = hmac_new_func(key, *args, **hmac_new_kwds) + h.update(msg) + self.check_hexdigest(h, hexdigest, digest_size) + + with self.subTest('no initial message'): + hmac_new_feed() + with self.subTest('initial message is empty'): + hmac_new_feed(b'') + with self.subTest('initial message is None'): + hmac_new_feed(None) + + def assert_hmac_hexdigest( + self, key, msg, hexdigest, digestmod, digest_size, + ): + """Check a HMAC digest computed by hmac_digest().""" + self.check_hmac_hexdigest( + key, msg, hexdigest, digest_size, + hmac_digest_func=self.hmac_digest, + hmac_digest_kwds={'digestmod': digestmod}, + ) - h = hmac.new(key, data, digestmod=hashname) - self.assert_hmac_internals( - h, digest, hashname, digest_size, block_size + def assert_hmac_hexdigest_by_name( + self, key, msg, hexdigest, hashname, digest_size + ): + """Check a HMAC digest computed by hmac_digest_by_name().""" + self.assertIsInstance(hashname, str) + self.check_hmac_hexdigest( + key, msg, hexdigest, digest_size, + hmac_digest_func=self.hmac_digest_by_name, + hmac_digest_kwds={'hashname': hashname}, ) - h = hmac.new(key, None, digestmod=hashname) - h.update(data) - self.assertEqual(h.hexdigest().upper(), digest.upper()) + def check_hmac_hexdigest( + self, key, msg, hexdigest, digest_size, + hmac_digest_func, hmac_digest_kwds=types.MappingProxyType({}), + ): + """Check and return a HMAC digest computed by hmac_digest_func(). - h = hmac.new(key, digestmod=hashname) - h.update(data) - self.assertEqual(h.hexdigest().upper(), digest.upper()) + This HMAC digest is computed by: - h = hmac.new(key, data, digestmod=hashfunc) - self.assertEqual(h.hexdigest().upper(), digest.upper()) + hmac_digest_func(key, msg, **hmac_digest_kwds) - self.assertEqual( - hmac.digest(key, data, digest=hashname), - binascii.unhexlify(digest) - ) - self.assertEqual( - hmac.digest(key, data, digest=hashfunc), - binascii.unhexlify(digest) - ) + This is typically useful for checking one-shot HMAC functions. + """ + d = hmac_digest_func(key, msg, **hmac_digest_kwds) + self.assertEqual(len(d), digest_size) + self.assertEqual(d, binascii.unhexlify(hexdigest)) + return d - h = hmac.HMAC.__new__(hmac.HMAC) - h._init_old(key, data, digestmod=hashname) - self.assert_hmac_internals( - h, digest, hashname, digest_size, block_size - ) + def assert_hmac_common_cases( + self, key, msg, hexdigest, digestmod, hashname, digest_size, block_size + ): + """Common tests executed by all subclasses.""" + h1 = self.hmac_new_by_name(key, hashname=hashname) + h2 = h1.copy() + h2.update(b"test update should not affect original") + h1.update(msg) + self.check_object(h1, hexdigest, hashname, digest_size, block_size) - if c_hmac_new is not None: - h = c_hmac_new(key, data, digestmod=hashname) - self.assert_hmac_internals( - h, digest, hashname, digest_size, block_size - ) + def assert_hmac_extra_cases( + self, key, msg, hexdigest, digestmod, hashname, digest_size, block_size + ): + """Extra tests that can be added in subclasses.""" - h = c_hmac_new(key, digestmod=hashname) - h2 = h.copy() - h2.update(b"test update") - h.update(data) - self.assertEqual(h.hexdigest().upper(), digest.upper()) - func = getattr(_hashopenssl, f"openssl_{hashname}") - h = c_hmac_new(key, data, digestmod=func) - self.assert_hmac_internals( - h, digest, hashname, digest_size, block_size - ) +class PyAssertersMixin(PyModuleMixin, AssertersMixin): - h = hmac.HMAC.__new__(hmac.HMAC) - h._init_hmac(key, data, digestmod=hashname) - self.assert_hmac_internals( - h, digest, hashname, digest_size, block_size - ) + def assert_hmac_extra_cases( + self, key, msg, hexdigest, digestmod, hashname, digest_size, block_size + ): + h = self.hmac.HMAC.__new__(self.hmac.HMAC) + h._init_old(key, msg, digestmod=digestmod) + self.check_object(h, hexdigest, hashname, digest_size, block_size) - # TODO: RUSTPYTHON - @unittest.expectedFailure - @hashlib_helper.requires_hashdigest('md5', openssl=True) - def test_md5_vectors(self): - # Test the HMAC module against test vectors from the RFC. - def md5test(key, data, digest): - self.assert_hmac( - key, data, digest, - hashfunc=hashlib.md5, - hashname="md5", - digest_size=16, - block_size=64 - ) +class OpenSSLAssertersMixin(ThroughOpenSSLAPIMixin, AssertersMixin): + + def hmac_new_by_name(self, key, msg=None, *, hashname): + self.assertIsInstance(hashname, str) + openssl_func = getattr(_hashlib, f"openssl_{hashname}") + return self.hmac_new(key, msg, digestmod=openssl_func) + + def hmac_digest_by_name(self, key, msg=None, *, hashname): + self.assertIsInstance(hashname, str) + openssl_func = getattr(_hashlib, f"openssl_{hashname}") + return self.hmac_digest(key, msg, digestmod=openssl_func) + + +class BuiltinAssertersMixin(ThroughBuiltinAPIMixin, AssertersMixin): + pass + + +class RFCTestCaseMixin(HashFunctionsTrait, AssertersMixin): + """Test HMAC implementations against RFC 2202/4231 and NIST test vectors. + + - Test vectors for MD5 and SHA-1 are taken from RFC 2202. + - Test vectors for SHA-2 are taken from RFC 4231. + - Test vectors for SHA-3 are NIST's test vectors [1]. + + [1] https://csrc.nist.gov/projects/message-authentication-codes + """ + + def test_md5_rfc2202(self): + def md5test(key, msg, hexdigest): + self.assert_hmac(key, msg, hexdigest, self.md5, "md5", 16, 64) md5test(b"\x0b" * 16, b"Hi There", - "9294727A3638BB1C13F48EF8158BFC9D") + "9294727a3638bb1c13f48ef8158bfc9d") md5test(b"Jefe", b"what do ya want for nothing?", @@ -170,18 +450,9 @@ def md5test(key, data, digest): b"and Larger Than One Block-Size Data"), "6f630fad67cda0ee1fb1f562db3aa53e") - # TODO: RUSTPYTHON - @unittest.expectedFailure - @hashlib_helper.requires_hashdigest('sha1', openssl=True) - def test_sha_vectors(self): - def shatest(key, data, digest): - self.assert_hmac( - key, data, digest, - hashfunc=hashlib.sha1, - hashname="sha1", - digest_size=20, - block_size=64 - ) + def test_sha1_rfc2202(self): + def shatest(key, msg, hexdigest): + self.assert_hmac(key, msg, hexdigest, self.sha1, "sha1", 20, 64) shatest(b"\x0b" * 20, b"Hi There", @@ -212,498 +483,1191 @@ def shatest(key, data, digest): b"and Larger Than One Block-Size Data"), "e8e99d0f45237d786d6bbaa7965c7808bbff1a91") - def _rfc4231_test_cases(self, hashfunc, hash_name, digest_size, block_size): - def hmactest(key, data, hexdigests): - digest = hexdigests[hashfunc] + def test_sha2_224_rfc4231(self): + self._test_sha2_rfc4231(self.sha224, 'sha224', 28, 64) + + def test_sha2_256_rfc4231(self): + self._test_sha2_rfc4231(self.sha256, 'sha256', 32, 64) + + def test_sha2_384_rfc4231(self): + self._test_sha2_rfc4231(self.sha384, 'sha384', 48, 128) + + def test_sha2_512_rfc4231(self): + self._test_sha2_rfc4231(self.sha512, 'sha512', 64, 128) + + def _test_sha2_rfc4231(self, hashfunc, hashname, digest_size, block_size): + def hmactest(key, msg, hexdigests): + hexdigest = hexdigests[hashname] self.assert_hmac( - key, data, digest, + key, msg, hexdigest, hashfunc=hashfunc, - hashname=hash_name, + hashname=hashname, digest_size=digest_size, block_size=block_size ) # 4.2. Test Case 1 - hmactest(key = b'\x0b'*20, - data = b'Hi There', - hexdigests = { - hashlib.sha224: '896fb1128abbdf196832107cd49df33f' - '47b4b1169912ba4f53684b22', - hashlib.sha256: 'b0344c61d8db38535ca8afceaf0bf12b' - '881dc200c9833da726e9376c2e32cff7', - hashlib.sha384: 'afd03944d84895626b0825f4ab46907f' - '15f9dadbe4101ec682aa034c7cebc59c' - 'faea9ea9076ede7f4af152e8b2fa9cb6', - hashlib.sha512: '87aa7cdea5ef619d4ff0b4241a1d6cb0' - '2379f4e2ce4ec2787ad0b30545e17cde' - 'daa833b7d6b8a702038b274eaea3f4e4' - 'be9d914eeb61f1702e696c203a126854', + hmactest(key=b'\x0b' * 20, + msg=b'Hi There', + hexdigests={ + 'sha224': '896fb1128abbdf196832107cd49df33f' + '47b4b1169912ba4f53684b22', + 'sha256': 'b0344c61d8db38535ca8afceaf0bf12b' + '881dc200c9833da726e9376c2e32cff7', + 'sha384': 'afd03944d84895626b0825f4ab46907f' + '15f9dadbe4101ec682aa034c7cebc59c' + 'faea9ea9076ede7f4af152e8b2fa9cb6', + 'sha512': '87aa7cdea5ef619d4ff0b4241a1d6cb0' + '2379f4e2ce4ec2787ad0b30545e17cde' + 'daa833b7d6b8a702038b274eaea3f4e4' + 'be9d914eeb61f1702e696c203a126854', }) # 4.3. Test Case 2 - hmactest(key = b'Jefe', - data = b'what do ya want for nothing?', - hexdigests = { - hashlib.sha224: 'a30e01098bc6dbbf45690f3a7e9e6d0f' - '8bbea2a39e6148008fd05e44', - hashlib.sha256: '5bdcc146bf60754e6a042426089575c7' - '5a003f089d2739839dec58b964ec3843', - hashlib.sha384: 'af45d2e376484031617f78d2b58a6b1b' - '9c7ef464f5a01b47e42ec3736322445e' - '8e2240ca5e69e2c78b3239ecfab21649', - hashlib.sha512: '164b7a7bfcf819e2e395fbe73b56e0a3' - '87bd64222e831fd610270cd7ea250554' - '9758bf75c05a994a6d034f65f8f0e6fd' - 'caeab1a34d4a6b4b636e070a38bce737', + hmactest(key=b'Jefe', + msg=b'what do ya want for nothing?', + hexdigests={ + 'sha224': 'a30e01098bc6dbbf45690f3a7e9e6d0f' + '8bbea2a39e6148008fd05e44', + 'sha256': '5bdcc146bf60754e6a042426089575c7' + '5a003f089d2739839dec58b964ec3843', + 'sha384': 'af45d2e376484031617f78d2b58a6b1b' + '9c7ef464f5a01b47e42ec3736322445e' + '8e2240ca5e69e2c78b3239ecfab21649', + 'sha512': '164b7a7bfcf819e2e395fbe73b56e0a3' + '87bd64222e831fd610270cd7ea250554' + '9758bf75c05a994a6d034f65f8f0e6fd' + 'caeab1a34d4a6b4b636e070a38bce737', }) # 4.4. Test Case 3 - hmactest(key = b'\xaa'*20, - data = b'\xdd'*50, - hexdigests = { - hashlib.sha224: '7fb3cb3588c6c1f6ffa9694d7d6ad264' - '9365b0c1f65d69d1ec8333ea', - hashlib.sha256: '773ea91e36800e46854db8ebd09181a7' - '2959098b3ef8c122d9635514ced565fe', - hashlib.sha384: '88062608d3e6ad8a0aa2ace014c8a86f' - '0aa635d947ac9febe83ef4e55966144b' - '2a5ab39dc13814b94e3ab6e101a34f27', - hashlib.sha512: 'fa73b0089d56a284efb0f0756c890be9' - 'b1b5dbdd8ee81a3655f83e33b2279d39' - 'bf3e848279a722c806b485a47e67c807' - 'b946a337bee8942674278859e13292fb', + hmactest(key=b'\xaa' * 20, + msg=b'\xdd' * 50, + hexdigests={ + 'sha224': '7fb3cb3588c6c1f6ffa9694d7d6ad264' + '9365b0c1f65d69d1ec8333ea', + 'sha256': '773ea91e36800e46854db8ebd09181a7' + '2959098b3ef8c122d9635514ced565fe', + 'sha384': '88062608d3e6ad8a0aa2ace014c8a86f' + '0aa635d947ac9febe83ef4e55966144b' + '2a5ab39dc13814b94e3ab6e101a34f27', + 'sha512': 'fa73b0089d56a284efb0f0756c890be9' + 'b1b5dbdd8ee81a3655f83e33b2279d39' + 'bf3e848279a722c806b485a47e67c807' + 'b946a337bee8942674278859e13292fb', }) # 4.5. Test Case 4 - hmactest(key = bytes(x for x in range(0x01, 0x19+1)), - data = b'\xcd'*50, - hexdigests = { - hashlib.sha224: '6c11506874013cac6a2abc1bb382627c' - 'ec6a90d86efc012de7afec5a', - hashlib.sha256: '82558a389a443c0ea4cc819899f2083a' - '85f0faa3e578f8077a2e3ff46729665b', - hashlib.sha384: '3e8a69b7783c25851933ab6290af6ca7' - '7a9981480850009cc5577c6e1f573b4e' - '6801dd23c4a7d679ccf8a386c674cffb', - hashlib.sha512: 'b0ba465637458c6990e5a8c5f61d4af7' - 'e576d97ff94b872de76f8050361ee3db' - 'a91ca5c11aa25eb4d679275cc5788063' - 'a5f19741120c4f2de2adebeb10a298dd', + hmactest(key=bytes(x for x in range(0x01, 0x19 + 1)), + msg=b'\xcd' * 50, + hexdigests={ + 'sha224': '6c11506874013cac6a2abc1bb382627c' + 'ec6a90d86efc012de7afec5a', + 'sha256': '82558a389a443c0ea4cc819899f2083a' + '85f0faa3e578f8077a2e3ff46729665b', + 'sha384': '3e8a69b7783c25851933ab6290af6ca7' + '7a9981480850009cc5577c6e1f573b4e' + '6801dd23c4a7d679ccf8a386c674cffb', + 'sha512': 'b0ba465637458c6990e5a8c5f61d4af7' + 'e576d97ff94b872de76f8050361ee3db' + 'a91ca5c11aa25eb4d679275cc5788063' + 'a5f19741120c4f2de2adebeb10a298dd', }) # 4.7. Test Case 6 - hmactest(key = b'\xaa'*131, - data = b'Test Using Larger Than Block-Siz' - b'e Key - Hash Key First', - hexdigests = { - hashlib.sha224: '95e9a0db962095adaebe9b2d6f0dbce2' - 'd499f112f2d2b7273fa6870e', - hashlib.sha256: '60e431591ee0b67f0d8a26aacbf5b77f' - '8e0bc6213728c5140546040f0ee37f54', - hashlib.sha384: '4ece084485813e9088d2c63a041bc5b4' - '4f9ef1012a2b588f3cd11f05033ac4c6' - '0c2ef6ab4030fe8296248df163f44952', - hashlib.sha512: '80b24263c7c1a3ebb71493c1dd7be8b4' - '9b46d1f41b4aeec1121b013783f8f352' - '6b56d037e05f2598bd0fd2215d6a1e52' - '95e64f73f63f0aec8b915a985d786598', + hmactest(key=b'\xaa' * 131, + msg=b'Test Using Larger Than Block-Siz' + b'e Key - Hash Key First', + hexdigests={ + 'sha224': '95e9a0db962095adaebe9b2d6f0dbce2' + 'd499f112f2d2b7273fa6870e', + 'sha256': '60e431591ee0b67f0d8a26aacbf5b77f' + '8e0bc6213728c5140546040f0ee37f54', + 'sha384': '4ece084485813e9088d2c63a041bc5b4' + '4f9ef1012a2b588f3cd11f05033ac4c6' + '0c2ef6ab4030fe8296248df163f44952', + 'sha512': '80b24263c7c1a3ebb71493c1dd7be8b4' + '9b46d1f41b4aeec1121b013783f8f352' + '6b56d037e05f2598bd0fd2215d6a1e52' + '95e64f73f63f0aec8b915a985d786598', }) # 4.8. Test Case 7 - hmactest(key = b'\xaa'*131, - data = b'This is a test using a larger th' - b'an block-size key and a larger t' - b'han block-size data. The key nee' - b'ds to be hashed before being use' - b'd by the HMAC algorithm.', - hexdigests = { - hashlib.sha224: '3a854166ac5d9f023f54d517d0b39dbd' - '946770db9c2b95c9f6f565d1', - hashlib.sha256: '9b09ffa71b942fcb27635fbcd5b0e944' - 'bfdc63644f0713938a7f51535c3a35e2', - hashlib.sha384: '6617178e941f020d351e2f254e8fd32c' - '602420feb0b8fb9adccebb82461e99c5' - 'a678cc31e799176d3860e6110c46523e', - hashlib.sha512: 'e37b6a775dc87dbaa4dfa9f96e5e3ffd' - 'debd71f8867289865df5a32d20cdc944' - 'b6022cac3c4982b10d5eeb55c3e4de15' - '134676fb6de0446065c97440fa8c6a58', + hmactest(key=b'\xaa' * 131, + msg=b'This is a test using a larger th' + b'an block-size key and a larger t' + b'han block-size data. The key nee' + b'ds to be hashed before being use' + b'd by the HMAC algorithm.', + hexdigests={ + 'sha224': '3a854166ac5d9f023f54d517d0b39dbd' + '946770db9c2b95c9f6f565d1', + 'sha256': '9b09ffa71b942fcb27635fbcd5b0e944' + 'bfdc63644f0713938a7f51535c3a35e2', + 'sha384': '6617178e941f020d351e2f254e8fd32c' + '602420feb0b8fb9adccebb82461e99c5' + 'a678cc31e799176d3860e6110c46523e', + 'sha512': 'e37b6a775dc87dbaa4dfa9f96e5e3ffd' + 'debd71f8867289865df5a32d20cdc944' + 'b6022cac3c4982b10d5eeb55c3e4de15' + '134676fb6de0446065c97440fa8c6a58', }) - # TODO: RUSTPYTHON - @unittest.expectedFailure - @hashlib_helper.requires_hashdigest('sha224', openssl=True) - def test_sha224_rfc4231(self): - self._rfc4231_test_cases(hashlib.sha224, 'sha224', 28, 64) - - # TODO: RUSTPYTHON - @unittest.expectedFailure - @hashlib_helper.requires_hashdigest('sha256', openssl=True) - def test_sha256_rfc4231(self): - self._rfc4231_test_cases(hashlib.sha256, 'sha256', 32, 64) - - # TODO: RUSTPYTHON - @unittest.expectedFailure - @hashlib_helper.requires_hashdigest('sha384', openssl=True) - def test_sha384_rfc4231(self): - self._rfc4231_test_cases(hashlib.sha384, 'sha384', 48, 128) - - # TODO: RUSTPYTHON - @unittest.expectedFailure - @hashlib_helper.requires_hashdigest('sha512', openssl=True) - def test_sha512_rfc4231(self): - self._rfc4231_test_cases(hashlib.sha512, 'sha512', 64, 128) + def test_sha3_224_nist(self): + for key, msg, hexdigest in [ + ( + bytes(range(28)), + b'Sample message for keylenblocklen', + '078695eecc227c636ad31d063a15dd05a7e819a66ec6d8de1e193e59' + ) + ]: + self.assert_hmac( + key, msg, hexdigest, + hashfunc=self.sha3_224, hashname='sha3_224', + digest_size=28, block_size=144 + ) - @hashlib_helper.requires_hashdigest('sha256') - def test_legacy_block_size_warnings(self): - class MockCrazyHash(object): - """Ain't no block_size attribute here.""" - def __init__(self, *args): - self._x = hashlib.sha256(*args) - self.digest_size = self._x.digest_size - def update(self, v): - self._x.update(v) - def digest(self): - return self._x.digest() + def test_sha3_256_nist(self): + for key, msg, hexdigest in [ + ( + bytes(range(32)), + b'Sample message for keylenblocklen', + '9bcf2c238e235c3ce88404e813bd2f3a' + '97185ac6f238c63d6229a00b07974258' + ) + ]: + self.assert_hmac( + key, msg, hexdigest, + hashfunc=self.sha3_256, hashname='sha3_256', + digest_size=32, block_size=136 + ) - with warnings.catch_warnings(): - warnings.simplefilter('error', RuntimeWarning) - with self.assertRaises(RuntimeWarning): - hmac.HMAC(b'a', b'b', digestmod=MockCrazyHash) - self.fail('Expected warning about missing block_size') + def test_sha3_384_nist(self): + for key, msg, hexdigest in [ + ( + bytes(range(48)), + b'Sample message for keylenblocklen', + 'e5ae4c739f455279368ebf36d4f5354c' + '95aa184c899d3870e460ebc288ef1f94' + '70053f73f7c6da2a71bcaec38ce7d6ac' + ) + ]: + self.assert_hmac( + key, msg, hexdigest, + hashfunc=self.sha3_384, hashname='sha3_384', + digest_size=48, block_size=104 + ) - MockCrazyHash.block_size = 1 - with self.assertRaises(RuntimeWarning): - hmac.HMAC(b'a', b'b', digestmod=MockCrazyHash) - self.fail('Expected warning about small block_size') + def test_sha3_512_nist(self): + for key, msg, hexdigest in [ + ( + bytes(range(64)), + b'Sample message for keylenblocklen', + '5f464f5e5b7848e3885e49b2c385f069' + '4985d0e38966242dc4a5fe3fea4b37d4' + '6b65ceced5dcf59438dd840bab22269f' + '0ba7febdb9fcf74602a35666b2a32915' + ) + ]: + self.assert_hmac( + key, msg, hexdigest, + hashfunc=self.sha3_512, hashname='sha3_512', + digest_size=64, block_size=72 + ) - def test_with_digestmod_no_default(self): - """The digestmod parameter is required as of Python 3.8.""" - with self.assertRaisesRegex(TypeError, r'required.*digestmod'): - key = b"\x0b" * 16 - data = b"Hi There" - hmac.HMAC(key, data, digestmod=None) - with self.assertRaisesRegex(TypeError, r'required.*digestmod'): - hmac.new(key, data) - with self.assertRaisesRegex(TypeError, r'required.*digestmod'): - hmac.HMAC(key, msg=data, digestmod='') - - # TODO: RUSTPYTHON - @unittest.expectedFailure - def test_with_fallback(self): - cache = getattr(hashlib, '__builtin_constructor_cache') - try: - cache['foo'] = hashlib.sha256 - hexdigest = hmac.digest(b'key', b'message', 'foo').hex() - expected = '6e9ef29b75fffc5b7abae527d58fdadb2fe42e7219011976917343065f58ed4a' - self.assertEqual(hexdigest, expected) - finally: - cache.pop('foo') +class PurePythonInitHMAC(PyModuleMixin, HashFunctionsTrait): + + @classmethod + def setUpClass(cls): + super().setUpClass() + for meth in ['_init_openssl_hmac', '_init_builtin_hmac']: + fn = getattr(cls.hmac.HMAC, meth) + cm = patch.object(cls.hmac.HMAC, meth, autospec=True, wraps=fn) + cls.enterClassContext(cm) + + @classmethod + def tearDownClass(cls): + cls.hmac.HMAC._init_openssl_hmac.assert_not_called() + cls.hmac.HMAC._init_builtin_hmac.assert_not_called() + # Do not assert that HMAC._init_old() has been called as it's tricky + # to determine whether a test for a specific hash function has been + # executed or not. On regular builds, it will be called but if a + # hash function is not available, it's hard to detect for which + # test we should checj HMAC._init_old() or not. + super().tearDownClass() + + +class PyRFCOpenSSLTestCase(ThroughObjectMixin, + PyAssertersMixin, + OpenSSLHashFunctionsTrait, + RFCTestCaseMixin, + PurePythonInitHMAC, + unittest.TestCase): + """Python implementation of HMAC using hmac.HMAC(). + + The underlying hash functions are OpenSSL-based but + _init_old() is used instead of _init_openssl_hmac(). + """ + + +class PyRFCBuiltinTestCase(ThroughObjectMixin, + PyAssertersMixin, + BuiltinHashFunctionsTrait, + RFCTestCaseMixin, + PurePythonInitHMAC, + unittest.TestCase): + """Python implementation of HMAC using hmac.HMAC(). + + The underlying hash functions are HACL*-based but + _init_old() is used instead of _init_builtin_hmac(). + """ + + +class PyDotNewOpenSSLRFCTestCase(ThroughModuleAPIMixin, + PyAssertersMixin, + OpenSSLHashFunctionsTrait, + RFCTestCaseMixin, + PurePythonInitHMAC, + unittest.TestCase): + """Python implementation of HMAC using hmac.new(). + + The underlying hash functions are OpenSSL-based but + _init_old() is used instead of _init_openssl_hmac(). + """ + + +class PyDotNewBuiltinRFCTestCase(ThroughModuleAPIMixin, + PyAssertersMixin, + BuiltinHashFunctionsTrait, + RFCTestCaseMixin, + PurePythonInitHMAC, + unittest.TestCase): + """Python implementation of HMAC using hmac.new(). + + The underlying hash functions are HACL-based but + _init_old() is used instead of _init_openssl_hmac(). + """ + + +class OpenSSLRFCTestCase(OpenSSLAssertersMixin, + OpenSSLHashFunctionsTrait, + RFCTestCaseMixin, + unittest.TestCase): + """OpenSSL implementation of HMAC. + + The underlying hash functions are also OpenSSL-based. + """ + + @unittest.expectedFailure # TODO: RUSTPYTHON; _hashlib.UnsupportedDigestmodError: unsupported hash type + def test_md5_rfc2202(self): + return super().test_md5_rfc2202() + + @unittest.expectedFailure # TODO: RUSTPYTHON; _hashlib.UnsupportedDigestmodError: unsupported hash type + def test_sha1_rfc2202(self): + return super().test_sha1_rfc2202() + + @unittest.expectedFailure # TODO: RUSTPYTHON; _hashlib.UnsupportedDigestmodError: unsupported hash type + def test_sha2_224_rfc4231(self): + return super().test_sha2_224_rfc4231() + + @unittest.expectedFailure # TODO: RUSTPYTHON; _hashlib.UnsupportedDigestmodError: unsupported hash type + def test_sha2_256_rfc4231(self): + return super().test_sha2_256_rfc4231() + + @unittest.expectedFailure # TODO: RUSTPYTHON; _hashlib.UnsupportedDigestmodError: unsupported hash type + def test_sha2_384_rfc4231(self): + return super().test_sha2_384_rfc4231() + + @unittest.expectedFailure # TODO: RUSTPYTHON; _hashlib.UnsupportedDigestmodError: unsupported hash type + def test_sha2_512_rfc4231(self): + return super().test_sha2_512_rfc4231() + + @unittest.expectedFailure # TODO: RUSTPYTHON; _hashlib.UnsupportedDigestmodError: unsupported hash type + def test_sha3_224_nist(self): + return super().test_sha3_224_nist() + + @unittest.expectedFailure # TODO: RUSTPYTHON; _hashlib.UnsupportedDigestmodError: unsupported hash type + def test_sha3_256_nist(self): + return super().test_sha3_256_nist() + + @unittest.expectedFailure # TODO: RUSTPYTHON; _hashlib.UnsupportedDigestmodError: unsupported hash type + def test_sha3_384_nist(self): + return super().test_sha3_384_nist() -class ConstructorTestCase(unittest.TestCase): + @unittest.expectedFailure # TODO: RUSTPYTHON; _hashlib.UnsupportedDigestmodError: unsupported hash type + def test_sha3_512_nist(self): + return super().test_sha3_512_nist() + + +class BuiltinRFCTestCase(BuiltinAssertersMixin, + NamedHashFunctionsTrait, + RFCTestCaseMixin, + unittest.TestCase): + """Built-in HACL* implementation of HMAC. - expected = ( - "6c845b47f52b3b47f6590c502db7825aad757bf4fadc8fa972f7cd2e76a5bdeb" - ) + The underlying hash functions are also HACL*-based. + """ - # TODO: RUSTPYTHON - @unittest.expectedFailure - @hashlib_helper.requires_hashdigest('sha256') - def test_normal(self): - # Standard constructor call. - try: - hmac.HMAC(b"key", digestmod='sha256') - except Exception: - self.fail("Standard constructor call raised exception.") + def assert_hmac_extra_cases( + self, key, msg, hexdigest, digestmod, hashname, digest_size, block_size + ): + # assert one-shot HMAC at the same time + with self.subTest(key=key, msg=msg, hashname=hashname): + func = getattr(self.hmac, f'compute_{hashname}') + self.assertTrue(callable(func)) + self.check_hmac_hexdigest(key, msg, hexdigest, digest_size, func) + + +class DigestModTestCaseMixin(CreatorMixin, DigestMixin): + """Tests for the 'digestmod' parameter for hmac_new() and hmac_digest().""" + + def assert_raises_missing_digestmod(self): + """A context manager catching errors when a digestmod is missing.""" + return self.assertRaisesRegex(TypeError, + "[M|m]issing.*required.*digestmod") + + def assert_raises_unknown_digestmod(self): + """A context manager catching errors when a digestmod is unknown.""" + return self.assertRaisesRegex(ValueError, "[Uu]nsupported.*") + + def test_constructor_missing_digestmod(self): + catcher = self.assert_raises_missing_digestmod + self.do_test_constructor_missing_digestmod(catcher) + + def test_constructor_unknown_digestmod(self): + catcher = self.assert_raises_unknown_digestmod + self.do_test_constructor_unknown_digestmod(catcher) - @hashlib_helper.requires_hashdigest('sha256') - def test_with_str_key(self): - # Pass a key of type str, which is an error, because it expects a key - # of type bytes - with self.assertRaises(TypeError): - h = hmac.HMAC("key", digestmod='sha256') + def do_test_constructor_missing_digestmod(self, catcher): + for func, args, kwds in self.cases_missing_digestmod_in_constructor(): + with self.subTest(args=args, kwds=kwds), catcher(): + func(*args, **kwds) - @hashlib_helper.requires_hashdigest('sha256') - def test_dot_new_with_str_key(self): - # Pass a key of type str, which is an error, because it expects a key - # of type bytes - with self.assertRaises(TypeError): - h = hmac.new("key", digestmod='sha256') + def do_test_constructor_unknown_digestmod(self, catcher): + for func, args, kwds in self.cases_unknown_digestmod_in_constructor(): + with self.subTest(args=args, kwds=kwds), catcher(): + func(*args, **kwds) - @hashlib_helper.requires_hashdigest('sha256') - def test_withtext(self): - # Constructor call with text. - try: - h = hmac.HMAC(b"key", b"hash this!", digestmod='sha256') - except Exception: - self.fail("Constructor call with text argument raised exception.") - self.assertEqual(h.hexdigest(), self.expected) + def cases_missing_digestmod_in_constructor(self): + raise NotImplementedError - @hashlib_helper.requires_hashdigest('sha256') - def test_with_bytearray(self): - try: - h = hmac.HMAC(bytearray(b"key"), bytearray(b"hash this!"), - digestmod="sha256") - except Exception: - self.fail("Constructor call with bytearray arguments raised exception.") - self.assertEqual(h.hexdigest(), self.expected) + def make_missing_digestmod_cases(self, func, missing_like=()): + """Generate cases for missing digestmod tests. - @hashlib_helper.requires_hashdigest('sha256') - def test_with_memoryview_msg(self): - try: - h = hmac.HMAC(b"key", memoryview(b"hash this!"), digestmod="sha256") - except Exception: - self.fail("Constructor call with memoryview msg raised exception.") - self.assertEqual(h.hexdigest(), self.expected) + Only the Python implementation should consider "falsey" 'digestmod' + values as being equivalent to a missing one. + """ + key, msg = b'unused key', b'unused msg' + choices = [DIGESTMOD_SENTINEL, *missing_like] + return self._invalid_digestmod_cases(func, key, msg, choices) - @hashlib_helper.requires_hashdigest('sha256') - def test_withmodule(self): - # Constructor call with text and digest module. - try: - h = hmac.HMAC(b"key", b"", hashlib.sha256) - except Exception: - self.fail("Constructor call with hashlib.sha256 raised exception.") + def cases_unknown_digestmod_in_constructor(self): + raise NotImplementedError + + def make_unknown_digestmod_cases(self, func, bad_digestmods): + """Generate cases for unknown digestmod tests.""" + key, msg = b'unused key', b'unused msg' + return self._invalid_digestmod_cases(func, key, msg, bad_digestmods) + + def _invalid_digestmod_cases(self, func, key, msg, choices): + cases = [] + for digestmod in choices: + kwargs = {'digestmod': digestmod} + cases.append((func, (key,), kwargs)) + cases.append((func, (key, msg), kwargs)) + cases.append((func, (key,), kwargs | {'msg': msg})) + return cases + + +class ConstructorTestCaseMixin(CreatorMixin, DigestMixin, ObjectCheckerMixin): + """HMAC constructor tests based on HMAC-SHA-2/256.""" + + key = b"key" + msg = b"hash this!" + res = "6c845b47f52b3b47f6590c502db7825aad757bf4fadc8fa972f7cd2e76a5bdeb" + + def do_test_constructor(self, hmac_on_key_and_msg): + self.do_test_constructor_invalid_types(hmac_on_key_and_msg) + self.do_test_constructor_supported_types(hmac_on_key_and_msg) + + def do_test_constructor_invalid_types(self, hmac_on_key_and_msg): + self.assertRaises(TypeError, hmac_on_key_and_msg, 1) + self.assertRaises(TypeError, hmac_on_key_and_msg, "key") + + self.assertRaises(TypeError, hmac_on_key_and_msg, b"key", 1) + self.assertRaises(TypeError, hmac_on_key_and_msg, b"key", "msg") + + def do_test_constructor_supported_types(self, hmac_on_key_and_msg): + for tp_key in [bytes, bytearray]: + for tp_msg in [bytes, bytearray, memoryview]: + with self.subTest(tp_key=tp_key, tp_msg=tp_msg): + h = hmac_on_key_and_msg(tp_key(self.key), tp_msg(self.msg)) + self.assertEqual(h.name, "hmac-sha256") + self.assertEqual(h.hexdigest(), self.res) + + @hashlib_helper.requires_hashdigest("sha256") + def test_constructor(self): + self.do_test_constructor(self.bind_hmac_new("sha256")) + + @hashlib_helper.requires_hashdigest("sha256") + def test_digest(self): + digest = self.hmac_digest(self.key, self.msg, "sha256") + self.assertEqual(digest, binascii.unhexlify(self.res)) + + +class PyConstructorBaseMixin(PyModuleMixin, + DigestModTestCaseMixin, + ConstructorTestCaseMixin): + + def cases_missing_digestmod_in_constructor(self): + func, choices = self.hmac_new, ['', None, False] + return self.make_missing_digestmod_cases(func, choices) + + def cases_unknown_digestmod_in_constructor(self): + func, choices = self.hmac_new, ['unknown'] + return self.make_unknown_digestmod_cases(func, choices) + + @requires_builtin_sha2() + def test_constructor_with_module(self): + self.do_test_constructor(self.bind_hmac_new(sha2.sha256)) + + @requires_builtin_sha2() + def test_digest_with_module(self): + digest = self.hmac_digest(self.key, self.msg, sha2.sha256) + self.assertEqual(digest, binascii.unhexlify(self.res)) + + +class PyConstructorTestCase(ThroughObjectMixin, PyConstructorBaseMixin, + unittest.TestCase): + """Test the hmac.HMAC() pure Python constructor.""" + + +class PyModuleConstructorTestCase(ThroughModuleAPIMixin, PyConstructorBaseMixin, + unittest.TestCase): + """Test the hmac.new() and hmac.digest() functions. + + Note that "self.hmac" is imported by blocking "_hashlib" and "_hmac". + For testing functions in "hmac", extend PyMiscellaneousTests instead. + """ + + def test_hmac_digest_digestmod_parameter(self): + func = self.hmac_digest + + def raiser(): + raise RuntimeError("custom exception") + + with self.assertRaisesRegex(RuntimeError, "custom exception"): + func(b'key', b'msg', raiser) + + with self.assertRaisesRegex(ValueError, 'hash type'): + func(b'key', b'msg', 'unknown') + + with self.assertRaisesRegex(AttributeError, 'new'): + func(b'key', b'msg', 1234) + with self.assertRaisesRegex(AttributeError, 'new'): + func(b'key', b'msg', None) + + +class ExtensionConstructorTestCaseMixin(DigestModTestCaseMixin, + ConstructorTestCaseMixin): + + @property + def obj_type(self): + """The underlying (non-instantiable) C class.""" + raise NotImplementedError + + @property + def exc_type(self): + """The exact exception class raised upon invalid 'digestmod' values.""" + raise NotImplementedError - # TODO: RUSTPYTHON - @unittest.expectedFailure - @unittest.skipUnless(C_HMAC is not None, 'need _hashlib') def test_internal_types(self): - # internal types like _hashlib.C_HMAC are not constructable - check_disallow_instantiation(self, C_HMAC) + # internal C types are immutable and cannot be instantiated + check_disallow_instantiation(self, self.obj_type) with self.assertRaisesRegex(TypeError, "immutable type"): - C_HMAC.value = None - - # TODO: RUSTPYTHON - @unittest.expectedFailure - @unittest.skipUnless(sha256_module is not None, 'need _sha256') - def test_with_sha256_module(self): - h = hmac.HMAC(b"key", b"hash this!", digestmod=sha256_module.sha256) - self.assertEqual(h.hexdigest(), self.expected) - self.assertEqual(h.name, "hmac-sha256") + self.obj_type.value = None - digest = hmac.digest(b"key", b"hash this!", sha256_module.sha256) - self.assertEqual(digest, binascii.unhexlify(self.expected)) + def assert_raises_unknown_digestmod(self): + self.assertIsSubclass(self.exc_type, ValueError) + return self.assertRaises(self.exc_type) + def cases_missing_digestmod_in_constructor(self): + return self.make_missing_digestmod_cases(self.hmac_new) -class SanityTestCase(unittest.TestCase): + def cases_unknown_digestmod_in_constructor(self): + func, choices = self.hmac_new, ['unknown', 1234] + return self.make_unknown_digestmod_cases(func, choices) - # TODO: RUSTPYTHON - @unittest.expectedFailure - @hashlib_helper.requires_hashdigest('sha256') - def test_exercise_all_methods(self): - # Exercising all methods once. - # This must not raise any exceptions - try: - h = hmac.HMAC(b"my secret key", digestmod="sha256") - h.update(b"compute the hash of this text!") - h.digest() - h.hexdigest() - h.copy() - except Exception: - self.fail("Exception raised during normal usage of HMAC class.") +class OpenSSLConstructorTestCase(ThroughOpenSSLAPIMixin, + ExtensionConstructorTestCaseMixin, + unittest.TestCase): -class UpdateTestCase(unittest.TestCase): - @hashlib_helper.requires_hashdigest('sha256') - def test_with_str_update(self): - with self.assertRaises(TypeError): - h = hmac.new(b"key", digestmod='sha256') - h.update("invalid update") + @property + def obj_type(self): + return _hashlib.HMAC + @property + def exc_type(self): + return _hashlib.UnsupportedDigestmodError -class CopyTestCase(unittest.TestCase): + @unittest.expectedFailure # TODO: RUSTPYTHON + def test_hmac_digest_digestmod_parameter(self): + for value in [object, 'unknown', 1234, None]: + with ( + self.subTest(value=value), + self.assert_raises_unknown_digestmod(), + ): + self.hmac_digest(b'key', b'msg', value) - @hashlib_helper.requires_hashdigest('sha256') - def test_attributes_old(self): + @unittest.expectedFailure # TODO: RUSTPYTHON + def test_constructor(self): + return super().test_constructor() + + @unittest.expectedFailure # TODO: RUSTPYTHON + def test_constructor_missing_digestmod(self): + return super().test_constructor_missing_digestmod() + + @unittest.expectedFailure # TODO: RUSTPYTHON + def test_constructor_unknown_digestmod(self): + return super().test_constructor_unknown_digestmod() + + @unittest.expectedFailure # TODO: RUSTPYTHON; AttributeError: module '_hashlib' has no attribute 'HMAC'. Did you mean: 'exc_type'? + def test_internal_types(self): + return super().test_internal_types() + + @unittest.expectedFailure # TODO: RUSTPYTHON; AttributeError: module '_hashlib' has no attribute 'hmac_digest' + def test_digest(self): + return super().test_digest() + + +class BuiltinConstructorTestCase(ThroughBuiltinAPIMixin, + ExtensionConstructorTestCaseMixin, + unittest.TestCase): + + @property + def obj_type(self): + return self.hmac.HMAC + + @property + def exc_type(self): + return self.hmac.UnknownHashError + + def test_hmac_digest_digestmod_parameter(self): + for value in [object, 'unknown', 1234, None]: + with ( + self.subTest(value=value), + self.assert_raises_unknown_digestmod(), + ): + self.hmac_digest(b'key', b'msg', value) + + +class SanityTestCaseMixin(CreatorMixin): + """Sanity checks for HMAC objects and their object interface. + + The tests here use a common digestname and do not check all supported + hash functions. + """ + + # The underlying HMAC class to test. May be in C or in Python. + hmac_class: type + # The underlying hash function name (should be accepted by the HMAC class). + digestname: str + # The expected digest and block sizes (must be hardcoded). + digest_size: int + block_size: int + + def test_methods(self): + h = self.hmac_new(b"my secret key", digestmod=self.digestname) + self.assertIsInstance(h, self.hmac_class) + self.assertIsNone(h.update(b"compute the hash of this text!")) + self.assertIsInstance(h.digest(), bytes) + self.assertIsInstance(h.hexdigest(), str) + self.assertIsInstance(h.copy(), self.hmac_class) + + def test_properties(self): + h = self.hmac_new(b"my secret key", digestmod=self.digestname) + self.assertEqual(h.name, f"hmac-{self.digestname}") + self.assertEqual(h.digest_size, self.digest_size) + self.assertEqual(h.block_size, self.block_size) + + def test_repr(self): + # HMAC object representation may differ across implementations + raise NotImplementedError + + +@hashlib_helper.requires_hashdigest('sha256') +class PySanityTestCase(ThroughObjectMixin, PyModuleMixin, SanityTestCaseMixin, + unittest.TestCase): + + @classmethod + def setUpClass(cls): + super().setUpClass() + cls.hmac_class = cls.hmac.HMAC + cls.digestname = 'sha256' + cls.digest_size = 32 + cls.block_size = 64 + + def test_repr(self): + h = self.hmac_new(b"my secret key", digestmod=self.digestname) + self.assertStartsWith(repr(h), "