Added CMAC docs
diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst
index 90deec8..2b92c43 100644
--- a/docs/hazmat/primitives/index.rst
+++ b/docs/hazmat/primitives/index.rst
@@ -7,7 +7,8 @@
:maxdepth: 1
cryptographic-hashes
- hmac
+ mac/hmac
+ mac/cmac
symmetric-encryption
padding
key-derivation-functions
diff --git a/docs/hazmat/primitives/mac/cmac.rst b/docs/hazmat/primitives/mac/cmac.rst
new file mode 100644
index 0000000..90d94ed
--- /dev/null
+++ b/docs/hazmat/primitives/mac/cmac.rst
@@ -0,0 +1,100 @@
+.. hazmat::
+
+Cipher-based message authentication code
+========================================
+
+.. currentmodule:: cryptography.hazmat.primitives.cmac
+
+.. testsetup::
+
+ import binascii
+ key = binascii.unhexlify(b"0" * 32)
+
+Cipher-based message authentication codes (or CMACs) are a tool for calculating
+message authentication codes using a block cipher coupled with a
+secret key. You can use an CMAC to verify both the integrity and authenticity
+of a message.
+
+.. class:: CMAC(algorithm, backend)
+
+ CMAC objects take a
+ :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` provider.
+
+ .. doctest::
+
+ >>> from cryptography.hazmat.backends import default_backend
+ >>> from cryptography.hazmat.primitives import cmac
+ >>> from cryptography.hazmat.primitives.ciphers import algorithms
+ >>> c = cmac.CMAC(algorithms.AES(key), backend=default_backend())
+ >>> c.update(b"message to authenticate")
+ >>> c.finalize()
+ 'CT\x1d\xc8\x0e\x15\xbe4e\xdb\xb6\x84\xca\xd9Xk'
+
+ If the backend doesn't support the requested ``algorithm`` an
+ :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be
+ raised.
+
+ If the `algorithm`` isn't a
+ :class:`~cryptography.primitives.interfaces.BlockCipherAlgorithm` provider,
+ ``TypeError`` will be raised.
+
+ To check that a given signature is correct use the :meth:`verify` method.
+ You will receive an exception if the signature is wrong:
+
+ .. code-block:: pycon
+
+ >>> c.verify(b"an incorrect signature")
+ Traceback (most recent call last):
+ ...
+ cryptography.exceptions.InvalidSignature: Signature did not match digest.
+
+ :param algorithm: An
+ :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm`
+ provider.
+ :param backend: An
+ :class:`~cryptography.hazmat.backends.interfaces.CMACBackend`
+ provider.
+ :raises TypeError: This is raised if the provided ``algorithm`` is not an instance of
+ :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm`
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
+ provided ``backend`` does not implement
+ :class:`~cryptography.hazmat.backends.interfaces.CMACBackend`
+
+ .. method:: update(data)
+
+ :param bytes data: The bytes to hash and authenticate.
+ :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
+
+ .. method:: copy()
+
+ Copy this :class:`CMAC` instance, usually so that we may call
+ :meth:`finalize` to get an intermediate value while we continue
+ to call :meth:`update` on the original instance.
+
+ :return: A new instance of :class:`CMAC` that can be updated
+ and finalized independently of the original instance.
+ :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
+
+ .. method:: verify(signature)
+
+ Finalize the current context and securely compare the MAC to
+ ``signature``.
+
+ :param bytes signature: The bytes to compare the current CMAC
+ against.
+ :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
+ :raises cryptography.exceptions.InvalidSignature: If signature does not
+ match digest
+
+ .. method:: finalize()
+
+ Finalize the current context and return the message authentication code
+ as bytes.
+
+ After ``finalize`` has been called this object can no longer be used
+ and :meth:`update`, :meth:`copy`, :meth:`verify` and :meth:`finalize`
+ will raise an :class:`~cryptography.exceptions.AlreadyFinalized`
+ exception.
+
+ :return bytes: The message authentication code as bytes.
+ :raises cryptography.exceptions.AlreadyFinalized:
diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/mac/hmac.rst
similarity index 100%
rename from docs/hazmat/primitives/hmac.rst
rename to docs/hazmat/primitives/mac/hmac.rst
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 1a4df22..c2692ae 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -21,7 +21,7 @@
decrypt them.
For this reason it is *strongly* recommended to combine encryption with a
-message authentication code, such as :doc:`HMAC </hazmat/primitives/hmac>`, in
+message authentication code, such as :doc:`HMAC </hazmat/primitives/mac/hmac>`, in
an "encrypt-then-MAC" formulation as `described by Colin Percival`_.
.. class:: Cipher(algorithm, mode, backend)
@@ -289,7 +289,7 @@
block cipher mode that simultaneously encrypts the message as well as
authenticating it. Additional unencrypted data may also be authenticated.
Additional means of verifying integrity such as
- :doc:`HMAC </hazmat/primitives/hmac>` are not necessary.
+ :doc:`HMAC </hazmat/primitives/mac/hmac>` are not necessary.
**This mode does not require padding.**