diff options
| -rw-r--r-- | cryptography/hazmat/bindings/openssl/backend.py | 40 | ||||
| -rw-r--r-- | cryptography/hazmat/primitives/hmac.py | 59 | ||||
| -rw-r--r-- | docs/hazmat/primitives/hmac.rst | 52 | ||||
| -rw-r--r-- | docs/hazmat/primitives/index.rst | 1 | ||||
| -rw-r--r-- | tests/hazmat/primitives/test_hmac.py | 57 | ||||
| -rw-r--r-- | tests/hazmat/primitives/test_hmac_vectors.py | 112 | ||||
| -rw-r--r-- | tests/hazmat/primitives/test_utils.py | 25 | ||||
| -rw-r--r-- | tests/hazmat/primitives/utils.py | 59 | ||||
| -rw-r--r-- | tests/test_utils.py | 16 | ||||
| -rw-r--r-- | tests/utils.py | 20 |
10 files changed, 436 insertions, 5 deletions
diff --git a/cryptography/hazmat/bindings/openssl/backend.py b/cryptography/hazmat/bindings/openssl/backend.py index 494430ba..635d6a0c 100644 --- a/cryptography/hazmat/bindings/openssl/backend.py +++ b/cryptography/hazmat/bindings/openssl/backend.py @@ -96,6 +96,7 @@ class Backend(object): self.ciphers = Ciphers(self) self.hashes = Hashes(self) + self.hmacs = HMACs(self) def openssl_version_text(self): """ @@ -259,4 +260,43 @@ class Hashes(object): return copied_ctx +class HMACs(object): + def __init__(self, backend): + super(HMACs, self).__init__() + self._backend = backend + + def create_ctx(self, key, hash_cls): + ctx = self._backend.ffi.new("HMAC_CTX *") + self._backend.lib.HMAC_CTX_init(ctx) + ctx = self._backend.ffi.gc(ctx, self._backend.lib.HMAC_CTX_cleanup) + evp_md = self._backend.lib.EVP_get_digestbyname( + hash_cls.name.encode('ascii')) + assert evp_md != self._backend.ffi.NULL + res = self._backend.lib.HMAC_Init_ex(ctx, key, len(key), evp_md, + self._backend.ffi.NULL) + assert res != 0 + return ctx + + def update_ctx(self, ctx, data): + res = self._backend.lib.HMAC_Update(ctx, data, len(data)) + assert res != 0 + + def finalize_ctx(self, ctx, digest_size): + buf = self._backend.ffi.new("unsigned char[]", digest_size) + buflen = self._backend.ffi.new("unsigned int *", digest_size) + res = self._backend.lib.HMAC_Final(ctx, buf, buflen) + assert res != 0 + self._backend.lib.HMAC_CTX_cleanup(ctx) + return self._backend.ffi.buffer(buf)[:digest_size] + + def copy_ctx(self, ctx): + copied_ctx = self._backend.ffi.new("HMAC_CTX *") + self._backend.lib.HMAC_CTX_init(copied_ctx) + copied_ctx = self._backend.ffi.gc(copied_ctx, + self._backend.lib.HMAC_CTX_cleanup) + res = self._backend.lib.HMAC_CTX_copy(copied_ctx, ctx) + assert res != 0 + return copied_ctx + + backend = Backend() diff --git a/cryptography/hazmat/primitives/hmac.py b/cryptography/hazmat/primitives/hmac.py new file mode 100644 index 00000000..4da0cc3f --- /dev/null +++ b/cryptography/hazmat/primitives/hmac.py @@ -0,0 +1,59 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import absolute_import, division, print_function + +import binascii + +import six + + +class HMAC(object): + def __init__(self, key, msg=None, digestmod=None, ctx=None, backend=None): + super(HMAC, self).__init__() + if backend is None: + from cryptography.hazmat.bindings import _default_backend + backend = _default_backend + + if digestmod is None: + raise TypeError("digestmod is a required argument") + + self._backend = backend + self.digestmod = digestmod + self.key = key + if ctx is None: + self._ctx = self._backend.hmacs.create_ctx(key, self.digestmod) + else: + self._ctx = ctx + + if msg is not None: + self.update(msg) + + def update(self, msg): + if isinstance(msg, six.text_type): + raise TypeError("Unicode-objects must be encoded before hashing") + self._backend.hmacs.update_ctx(self._ctx, msg) + + def copy(self): + return self.__class__(self.key, digestmod=self.digestmod, + backend=self._backend, ctx=self._copy_ctx()) + + def digest(self): + return self._backend.hmacs.finalize_ctx(self._copy_ctx(), + self.digestmod.digest_size) + + def hexdigest(self): + return str(binascii.hexlify(self.digest()).decode("ascii")) + + def _copy_ctx(self): + return self._backend.hmacs.copy_ctx(self._ctx) diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst new file mode 100644 index 00000000..bfbe3255 --- /dev/null +++ b/docs/hazmat/primitives/hmac.rst @@ -0,0 +1,52 @@ +.. danger:: + + This is a "Hazardous Materials" module. You should **ONLY** use it if + you're 100% absolutely sure that you know what you're doing because this + module is full of land mines, dragons, and dinosaurs with laser guns. + + +Hash-based Message Authentication Codes +======================================= + +.. testsetup:: + + import binascii + key = binascii.unhexlify(b"0" * 32) + +Hash-based message authentication codes (or HMACs) are a tool for calculating +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:: cryptography.hazmat.primitives.hmac.HMAC(key, msg=None, digestmod=None) + + HMAC objects take a ``key``, a hash class derived from + :class:`~cryptography.primitives.hashes.BaseHash`, and optional message. + 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. + + .. doctest:: + + >>> from cryptography.hazmat.primitives import hashes, hmac + >>> h = hmac.HMAC(key, digestmod=hashes.SHA256) + >>> h.update(b"message to hash") + >>> h.hexdigest() + '...' + + .. method:: update(msg) + + :param bytes msg: The bytes to hash and authenticate. + + .. method:: copy() + + :return: a new instance of this object with a copied internal state. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 6ae769a6..3927f3f0 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -12,4 +12,5 @@ Primitives :maxdepth: 1 cryptographic-hashes + hmac symmetric-encryption diff --git a/tests/hazmat/primitives/test_hmac.py b/tests/hazmat/primitives/test_hmac.py new file mode 100644 index 00000000..42726a7c --- /dev/null +++ b/tests/hazmat/primitives/test_hmac.py @@ -0,0 +1,57 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import absolute_import, division, print_function + +import pretend + +import pytest + +import six + +from cryptography.hazmat.primitives import hashes, hmac + +from .utils import generate_base_hmac_test + + +class TestHMAC(object): + test_copy = generate_base_hmac_test( + hashes.MD5, + only_if=lambda backend: backend.hashes.supported(hashes.MD5), + skip_message="Does not support MD5", + ) + + def test_hmac_reject_unicode(self, backend): + h = hmac.HMAC(key=b"mykey", digestmod=hashes.SHA1, backend=backend) + with pytest.raises(TypeError): + h.update(six.u("\u00FC")) + + def test_base_hash_hexdigest_string_type(self, backend): + h = hmac.HMAC(key=b"mykey", digestmod=hashes.SHA1, backend=backend, + msg=b"") + assert isinstance(h.hexdigest(), str) + + def test_hmac_no_digestmod(self): + with pytest.raises(TypeError): + hmac.HMAC(key=b"shortkey") + + +class TestCopyHMAC(object): + def test_copy_backend_object(self): + pretend_hmac = pretend.stub(copy_ctx=lambda a: True) + pretend_backend = pretend.stub(hmacs=pretend_hmac) + pretend_ctx = pretend.stub() + h = hmac.HMAC(b"key", digestmod=hashes.SHA1, backend=pretend_backend, + ctx=pretend_ctx) + assert h._backend is pretend_backend + assert h.copy()._backend is pretend_backend diff --git a/tests/hazmat/primitives/test_hmac_vectors.py b/tests/hazmat/primitives/test_hmac_vectors.py new file mode 100644 index 00000000..81fe4d3e --- /dev/null +++ b/tests/hazmat/primitives/test_hmac_vectors.py @@ -0,0 +1,112 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import absolute_import, division, print_function + +import os + +from cryptography.hazmat.primitives import hashes + +from .utils import generate_hmac_test +from ...utils import load_hash_vectors_from_file + + +class TestHMAC_MD5(object): + test_hmac_md5 = generate_hmac_test( + load_hash_vectors_from_file, + os.path.join("RFC", "HMAC"), + [ + "rfc-2202-md5.txt", + ], + hashes.MD5, + only_if=lambda backend: backend.hashes.supported(hashes.MD5), + skip_message="Does not support MD5", + ) + + +class TestHMAC_SHA1(object): + test_hmac_sha1 = generate_hmac_test( + load_hash_vectors_from_file, + os.path.join("RFC", "HMAC"), + [ + "rfc-2202-sha1.txt", + ], + hashes.SHA1, + only_if=lambda backend: backend.hashes.supported(hashes.SHA1), + skip_message="Does not support SHA1", + ) + + +class TestHMAC_SHA224(object): + test_hmac_sha224 = generate_hmac_test( + load_hash_vectors_from_file, + os.path.join("RFC", "HMAC"), + [ + "rfc-4231-sha224.txt", + ], + hashes.SHA224, + only_if=lambda backend: backend.hashes.supported(hashes.SHA224), + skip_message="Does not support SHA224", + ) + + +class TestHMAC_SHA256(object): + test_hmac_sha256 = generate_hmac_test( + load_hash_vectors_from_file, + os.path.join("RFC", "HMAC"), + [ + "rfc-4231-sha256.txt", + ], + hashes.SHA256, + only_if=lambda backend: backend.hashes.supported(hashes.SHA256), + skip_message="Does not support SHA256", + ) + + +class TestHMAC_SHA384(object): + test_hmac_sha384 = generate_hmac_test( + load_hash_vectors_from_file, + os.path.join("RFC", "HMAC"), + [ + "rfc-4231-sha384.txt", + ], + hashes.SHA384, + only_if=lambda backend: backend.hashes.supported(hashes.SHA384), + skip_message="Does not support SHA384", + ) + + +class TestHMAC_SHA512(object): + test_hmac_sha512 = generate_hmac_test( + load_hash_vectors_from_file, + os.path.join("RFC", "HMAC"), + [ + "rfc-4231-sha512.txt", + ], + hashes.SHA512, + only_if=lambda backend: backend.hashes.supported(hashes.SHA512), + skip_message="Does not support SHA512", + ) + + +class TestHMAC_RIPEMD160(object): + test_hmac_ripemd160 = generate_hmac_test( + load_hash_vectors_from_file, + os.path.join("RFC", "HMAC"), + [ + "rfc-2286-ripemd160.txt", + ], + hashes.RIPEMD160, + only_if=lambda backend: backend.hashes.supported(hashes.RIPEMD160), + skip_message="Does not support RIPEMD160", + ) diff --git a/tests/hazmat/primitives/test_utils.py b/tests/hazmat/primitives/test_utils.py index b7fa3d35..d7247e67 100644 --- a/tests/hazmat/primitives/test_utils.py +++ b/tests/hazmat/primitives/test_utils.py @@ -1,7 +1,8 @@ import pytest from .utils import ( - base_hash_test, encrypt_test, hash_test, long_string_hash_test + base_hash_test, encrypt_test, hash_test, long_string_hash_test, + base_hmac_test, hmac_test ) @@ -47,3 +48,25 @@ class TestLongHashTest(object): skip_message="message!" ) assert exc_info.value.args[0] == "message!" + + +class TestHMACTest(object): + def test_skips_if_only_if_returns_false(self): + with pytest.raises(pytest.skip.Exception) as exc_info: + hmac_test( + None, None, None, + only_if=lambda backend: False, + skip_message="message!" + ) + assert exc_info.value.args[0] == "message!" + + +class TestBaseHMACTest(object): + def test_skips_if_only_if_returns_false(self): + with pytest.raises(pytest.skip.Exception) as exc_info: + base_hmac_test( + None, None, + only_if=lambda backend: False, + skip_message="message!" + ) + assert exc_info.value.args[0] == "message!" diff --git a/tests/hazmat/primitives/utils.py b/tests/hazmat/primitives/utils.py index fabdca01..c51fef52 100644 --- a/tests/hazmat/primitives/utils.py +++ b/tests/hazmat/primitives/utils.py @@ -4,6 +4,7 @@ import os import pytest from cryptography.hazmat.bindings import _ALL_BACKENDS +from cryptography.hazmat.primitives import hmac from cryptography.hazmat.primitives.block import BlockCipher @@ -92,11 +93,11 @@ def generate_base_hash_test(hash_cls, digest_size, block_size, return test_base_hash -def base_hash_test(backend, hash_cls, digest_size, block_size, only_if, +def base_hash_test(backend, digestmod, digest_size, block_size, only_if, skip_message): if only_if is not None and not only_if(backend): pytest.skip(skip_message) - m = hash_cls(backend=backend) + m = digestmod(backend=backend) assert m.digest_size == digest_size assert m.block_size == block_size m_copy = m.copy() @@ -125,3 +126,57 @@ def long_string_hash_test(backend, hash_factory, md, only_if, skip_message): m = hash_factory(backend=backend) m.update(b"a" * 1000000) assert m.hexdigest() == md.lower() + + +def generate_hmac_test(param_loader, path, file_names, digestmod, + only_if=None, skip_message=None): + def test_hmac(self): + for backend in _ALL_BACKENDS: + for file_name in file_names: + for params in param_loader(os.path.join(path, file_name)): + yield ( + hmac_test, + backend, + digestmod, + params, + only_if, + skip_message + ) + return test_hmac + + +def hmac_test(backend, digestmod, params, only_if, skip_message): + if only_if is not None and not only_if(backend): + pytest.skip(skip_message) + msg = params[0] + md = params[1] + key = params[2] + h = hmac.HMAC(binascii.unhexlify(key), digestmod=digestmod) + h.update(binascii.unhexlify(msg)) + assert h.hexdigest() == md + digest = hmac.HMAC(binascii.unhexlify(key), digestmod=digestmod, + msg=binascii.unhexlify(msg)).hexdigest() + assert digest == md + + +def generate_base_hmac_test(hash_cls, only_if=None, skip_message=None): + def test_base_hmac(self): + for backend in _ALL_BACKENDS: + yield ( + base_hmac_test, + backend, + hash_cls, + only_if, + skip_message, + ) + return test_base_hmac + + +def base_hmac_test(backend, digestmod, only_if, skip_message): + if only_if is not None and not only_if(backend): + pytest.skip(skip_message) + key = b"ab" + h = hmac.HMAC(binascii.unhexlify(key), digestmod=digestmod) + h_copy = h.copy() + assert h != h_copy + assert h._ctx != h_copy._ctx diff --git a/tests/test_utils.py b/tests/test_utils.py index f96cf004..db9ac085 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -411,6 +411,22 @@ def test_load_hash_vectors(): ] +def test_load_hmac_vectors(): + vector_data = textwrap.dedent(""" +Len = 224 +# "Jefe" +Key = 4a656665 +# "what do ya want for nothing?" +Msg = 7768617420646f2079612077616e7420666f72206e6f7468696e673f +MD = 750c783e6ab0b503eaa86e310a5db738 + """).splitlines() + assert load_hash_vectors(vector_data) == [ + (b"7768617420646f2079612077616e7420666f72206e6f7468696e673f", + "750c783e6ab0b503eaa86e310a5db738", + b"4a656665"), + ] + + def test_load_hash_vectors_bad_data(): vector_data = textwrap.dedent(""" # http://tools.ietf.org/html/rfc1321 diff --git a/tests/utils.py b/tests/utils.py index 9d01746a..ad676c04 100644 --- a/tests/utils.py +++ b/tests/utils.py @@ -127,6 +127,9 @@ def load_openssl_vectors(vector_data): def load_hash_vectors(vector_data): vectors = [] + key = None + msg = None + md = None for line in vector_data: line = line.strip() @@ -136,6 +139,11 @@ def load_hash_vectors(vector_data): if line.startswith("Len"): length = int(line.split(" = ")[1]) + elif line.startswith("Key"): + """ + HMAC vectors contain a key attribute. Hash vectors do not. + """ + key = line.split(" = ")[1].encode("ascii") elif line.startswith("Msg"): """ In the NIST vectors they have chosen to represent an empty @@ -145,8 +153,16 @@ def load_hash_vectors(vector_data): msg = line.split(" = ")[1].encode("ascii") if length > 0 else b"" elif line.startswith("MD"): md = line.split(" = ")[1] - # after MD is found the Msg+MD tuple is complete - vectors.append((msg, md)) + # after MD is found the Msg+MD (+ potential key) tuple is complete + if key is not None: + vectors.append((msg, md, key)) + key = None + msg = None + md = None + else: + vectors.append((msg, md)) + msg = None + md = None else: raise ValueError("Unknown line in hash vector") return vectors |