Merge pull request #157 from reaperhulk/hmac
HMAC support
diff --git a/cryptography/hazmat/bindings/openssl/backend.py b/cryptography/hazmat/bindings/openssl/backend.py
index 494430b..635d6a0 100644
--- a/cryptography/hazmat/bindings/openssl/backend.py
+++ b/cryptography/hazmat/bindings/openssl/backend.py
@@ -96,6 +96,7 @@
self.ciphers = Ciphers(self)
self.hashes = Hashes(self)
+ self.hmacs = HMACs(self)
def openssl_version_text(self):
"""
@@ -259,4 +260,43 @@
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 0000000..4da0cc3
--- /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 0000000..bfbe325
--- /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 6ae769a..3927f3f 100644
--- a/docs/hazmat/primitives/index.rst
+++ b/docs/hazmat/primitives/index.rst
@@ -12,4 +12,5 @@
: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 0000000..42726a7
--- /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 0000000..81fe4d3
--- /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 b7fa3d3..d7247e6 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 @@
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 fabdca0..c51fef5 100644
--- a/tests/hazmat/primitives/utils.py
+++ b/tests/hazmat/primitives/utils.py
@@ -4,6 +4,7 @@
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 @@
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 @@
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 f96cf00..db9ac08 100644
--- a/tests/test_utils.py
+++ b/tests/test_utils.py
@@ -411,6 +411,22 @@
]
+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 9d01746..ad676c0 100644
--- a/tests/utils.py
+++ b/tests/utils.py
@@ -127,6 +127,9 @@
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 @@
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 @@
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