2 files changed, 51 insertions, 0 deletions
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