From 0317b04b119ceb55e11cf1be28c5223bad240c26 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 28 Oct 2013 17:34:27 -0500 Subject: HMAC support Conflicts: docs/primitives/index.rst tests/hazmat/primitives/utils.py --- docs/hazmat/primitives/hmac.rst | 50 ++++++++++++++++++++++++++++++++++++++++ docs/hazmat/primitives/index.rst | 1 + 2 files changed, 51 insertions(+) create mode 100644 docs/hazmat/primitives/hmac.rst (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst new file mode 100644 index 00000000..993e3179 --- /dev/null +++ b/docs/hazmat/primitives/hmac.rst @@ -0,0 +1,50 @@ +.. 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.primitives.hmac.HMAC(key, hash_cls, data=None) + + HMAC objects take a ``key``, a hash class derived from :class:`~cryptography.primitives.hashes.BaseHash`, + and optional initial data. The ``key`` should be randomly generated bytes and + the length of the ``block_size`` of the hash. You must keep the ``key`` secret. + + .. doctest:: + + >>> from cryptography.primitives import hashes, hmac + >>> h = hmac.HMAC(key, hashes.SHA1) + >>> h.update(b"message to hash") + >>> h.hexdigest() + '...' + + .. method:: update(data) + + :param bytes data: 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. + + .. 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 -- cgit v1.2.3 From 1bb8b710d444012b7218a08f098a85c4a31ca1bc Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 27 Oct 2013 17:00:14 -0500 Subject: clean up loader and make docs default to hmac sha256 --- docs/hazmat/primitives/hmac.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 993e3179..47b88030 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -27,7 +27,7 @@ message. .. doctest:: >>> from cryptography.primitives import hashes, hmac - >>> h = hmac.HMAC(key, hashes.SHA1) + >>> h = hmac.HMAC(key, hashes.SHA256) >>> h.update(b"message to hash") >>> h.hexdigest() '...' -- cgit v1.2.3 From 2824ab72d30e8423d17496e2c3baa47106505c8c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 28 Oct 2013 11:06:55 -0500 Subject: make hmac (mostly) compatible with stdlib hmac --- docs/hazmat/primitives/hmac.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 47b88030..76b7e24c 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -18,23 +18,23 @@ 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.primitives.hmac.HMAC(key, hash_cls, data=None) +.. class:: cryptography.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 initial data. The ``key`` should be randomly generated bytes and + and optional msg. The ``key`` should be randomly generated bytes and the length of the ``block_size`` of the hash. You must keep the ``key`` secret. .. doctest:: >>> from cryptography.primitives import hashes, hmac - >>> h = hmac.HMAC(key, hashes.SHA256) + >>> h = hmac.HMAC(key, digestmod=hashes.SHA256) >>> h.update(b"message to hash") >>> h.hexdigest() '...' - .. method:: update(data) + .. method:: update(msg) - :param bytes data: The bytes you wish to hash. + :param bytes msg The bytes you wish to hash. .. method:: copy() -- cgit v1.2.3 From 30eabddbade7647e0fb53500356e252eed245c6a Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 28 Oct 2013 12:52:47 -0500 Subject: change type of exception raised, fix docs typo --- docs/hazmat/primitives/hmac.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 76b7e24c..14aaf19f 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -34,7 +34,7 @@ message. .. method:: update(msg) - :param bytes msg The bytes you wish to hash. + :param bytes msg: The bytes you wish to hash. .. method:: copy() -- cgit v1.2.3 From bf8962a22b18e022085eec797ca64c1242564b21 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 28 Oct 2013 17:44:42 -0500 Subject: fix hmac docs to point to new hazmat location --- docs/hazmat/primitives/hmac.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 14aaf19f..702df2c7 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -18,7 +18,7 @@ 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.primitives.hmac.HMAC(key, msg=None, digestmod=None) +.. 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 msg. The ``key`` should be randomly generated bytes and @@ -26,7 +26,7 @@ message. .. doctest:: - >>> from cryptography.primitives import hashes, hmac + >>> from cryptography.hazmat.primitives import hashes, hmac >>> h = hmac.HMAC(key, digestmod=hashes.SHA256) >>> h.update(b"message to hash") >>> h.hexdigest() -- cgit v1.2.3 From ca8ed2953a1602fdceaee86d44b77d27f135926b Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 28 Oct 2013 19:37:39 -0500 Subject: fix indentation error and wrapping in docs --- docs/hazmat/primitives/hmac.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 702df2c7..aec406b9 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -20,9 +20,10 @@ 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 msg. The ``key`` should be randomly generated bytes and - the length of the ``block_size`` of the hash. You must keep the ``key`` secret. + HMAC objects take a ``key``, a hash class derived from + :class:`~cryptography.primitives.hashes.BaseHash`, and optional msg. The + ``key`` should be randomly generated bytes and the length of the + ``block_size`` of the hash. You must keep the ``key`` secret. .. doctest:: -- cgit v1.2.3 From 50a881572bc7617d4d49c4ae7b200c3bcb7398d9 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 29 Oct 2013 10:46:05 -0500 Subject: update hmac docs --- docs/hazmat/primitives/hmac.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index aec406b9..bfbe3255 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -21,9 +21,10 @@ 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 msg. The - ``key`` should be randomly generated bytes and the length of the - ``block_size`` of the hash. You must keep the ``key`` secret. + :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:: @@ -35,7 +36,7 @@ message. .. method:: update(msg) - :param bytes msg: The bytes you wish to hash. + :param bytes msg: The bytes to hash and authenticate. .. method:: copy() -- cgit v1.2.3