• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. hazmat::
2
3Cipher-based message authentication code (CMAC)
4===============================================
5
6.. currentmodule:: cryptography.hazmat.primitives.cmac
7
8.. testsetup::
9
10    import binascii
11    key = binascii.unhexlify(b"0" * 32)
12
13`Cipher-based message authentication codes`_ (or CMACs) are a tool for
14calculating message authentication codes using a block cipher coupled with a
15secret key. You can use an CMAC to verify both the integrity and authenticity
16of a message.
17
18A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`.
19
20.. class:: CMAC(algorithm, backend)
21
22    .. versionadded:: 0.4
23
24    CMAC objects take a
25    :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm` instance.
26
27    .. doctest::
28
29        >>> from cryptography.hazmat.backends import default_backend
30        >>> from cryptography.hazmat.primitives import cmac
31        >>> from cryptography.hazmat.primitives.ciphers import algorithms
32        >>> c = cmac.CMAC(algorithms.AES(key), backend=default_backend())
33        >>> c.update(b"message to authenticate")
34        >>> c.finalize()
35        b'CT\x1d\xc8\x0e\x15\xbe4e\xdb\xb6\x84\xca\xd9Xk'
36
37    If the backend doesn't support the requested ``algorithm`` an
38    :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be
39    raised.
40
41    If ``algorithm`` isn't a
42    :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm`
43    instance then ``TypeError`` will be raised.
44
45    To check that a given signature is correct use the :meth:`verify` method.
46    You will receive an exception if the signature is wrong:
47
48    .. doctest::
49
50        >>> c = cmac.CMAC(algorithms.AES(key), backend=default_backend())
51        >>> c.update(b"message to authenticate")
52        >>> c.verify(b"an incorrect signature")
53        Traceback (most recent call last):
54        ...
55        cryptography.exceptions.InvalidSignature: Signature did not match digest.
56
57    :param algorithm: An instance of
58        :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm`.
59    :param backend: An instance of
60        :class:`~cryptography.hazmat.backends.interfaces.CMACBackend`.
61    :raises TypeError: This is raised if the provided ``algorithm`` is not an instance of
62        :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm`
63    :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the
64        provided ``backend`` does not implement
65        :class:`~cryptography.hazmat.backends.interfaces.CMACBackend`
66
67    .. method:: update(data)
68
69        :param bytes data: The bytes to hash and authenticate.
70        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
71        :raises TypeError: This exception is raised if ``data`` is not ``bytes``.
72
73    .. method:: copy()
74
75        Copy this :class:`CMAC` instance, usually so that we may call
76        :meth:`finalize` to get an intermediate value while we continue
77        to call :meth:`update` on the original instance.
78
79        :return: A new instance of :class:`CMAC` that can be updated
80            and finalized independently of the original instance.
81        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
82
83    .. method:: verify(signature)
84
85        Finalize the current context and securely compare the MAC to
86        ``signature``.
87
88        :param bytes signature: The bytes to compare the current CMAC
89                against.
90        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
91        :raises cryptography.exceptions.InvalidSignature: If signature does not
92                                                                  match digest
93        :raises TypeError: This exception is raised if ``signature`` is not
94                           ``bytes``.
95
96        .. method:: finalize()
97
98        Finalize the current context and return the message authentication code
99        as bytes.
100
101        After ``finalize`` has been called this object can no longer be used
102        and :meth:`update`, :meth:`copy`, :meth:`verify` and :meth:`finalize`
103        will raise an :class:`~cryptography.exceptions.AlreadyFinalized`
104        exception.
105
106        :return bytes: The message authentication code as bytes.
107        :raises cryptography.exceptions.AlreadyFinalized:
108
109
110.. _`Cipher-based message authentication codes`: https://en.wikipedia.org/wiki/CMAC
111