move MACContext to mac.py and eliminate interfaces.py (#3631)

* move MACContext to mac.py and eliminate interfaces.py finally

* improve title

* re-add and deprecate interfaces.MACContext

* use pytest.warns instead of deprecated_call

The pytest docs insist that deprecation warnings are handled differently
and that you should use deprecated_call, but this works so okay then

3 files changed, 36 insertions, 4 deletions

diff --git a/docs/hazmat/primitives/mac/cmac.rst b/docs/hazmat/primitives/mac/cmac.rst
index e170db31..b316e4c3 100644
--- a/docs/hazmat/primitives/mac/cmac.rst
+++ b/docs/hazmat/primitives/mac/cmac.rst
@@ -1,7 +1,7 @@
 .. hazmat::
 
-Cipher-based message authentication code
-========================================
+Cipher-based message authentication code (CMAC)
+===============================================
 
 .. currentmodule:: cryptography.hazmat.primitives.cmac
 
diff --git a/docs/hazmat/primitives/mac/hmac.rst b/docs/hazmat/primitives/mac/hmac.rst
index e00c4de2..a0e2014d 100644
--- a/docs/hazmat/primitives/mac/hmac.rst
+++ b/docs/hazmat/primitives/mac/hmac.rst
@@ -1,7 +1,7 @@
 .. hazmat::
 
-Hash-based message authentication codes
-=======================================
+Hash-based message authentication codes (HMAC)
+==============================================
 
 .. currentmodule:: cryptography.hazmat.primitives.hmac
 
diff --git a/docs/hazmat/primitives/mac/index.rst b/docs/hazmat/primitives/mac/index.rst
index 05db708c..86c407c4 100644
--- a/docs/hazmat/primitives/mac/index.rst
+++ b/docs/hazmat/primitives/mac/index.rst
@@ -9,6 +9,38 @@ recommend that HMAC should be used unless you have a good reason otherwise.
 For more information on why HMAC is preferred, see `Use cases for CMAC vs.
 HMAC?`_
 
+HMAC and CMAC both use the ``MACContext`` interface:
+
+.. currentmodule:: cryptography.hazmat.primitives.mac
+
+.. class:: MACContext
+
+    .. versionadded:: 0.7
+
+    .. method:: update(data)
+
+        :param bytes data: The data you want to authenticate.
+
+    .. method:: finalize()
+
+        :return: The message authentication code.
+
+    .. method:: copy()
+
+        :return: A
+            :class:`~cryptography.hazmat.primitives.mac.MACContext` that
+            is a copy of the current context.
+
+    .. method:: verify(signature)
+
+        :param bytes signature: The signature to verify.
+
+        :raises cryptography.exceptions.InvalidSignature: This is raised when
+            the provided signature does not match the expected signature.
+
+
+
+.. _`CMAC`: https://en.wikipedia.org/wiki/CMAC
 .. _`Use cases for CMAC vs. HMAC?`: https://crypto.stackexchange.com/questions/15721/use-cases-for-cmac-vs-hmac
 
 .. toctree::