Merge branch 'master' into pkcs7-padding

2 files changed, 53 insertions, 0 deletions

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