diff options
Diffstat (limited to 'docs/hazmat/primitives/mac')
| -rw-r--r-- | docs/hazmat/primitives/mac/cmac.rst | 13 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/hmac.rst | 7 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/index.rst | 8 |
3 files changed, 23 insertions, 5 deletions
diff --git a/docs/hazmat/primitives/mac/cmac.rst b/docs/hazmat/primitives/mac/cmac.rst index a6b048b5..498b8b1e 100644 --- a/docs/hazmat/primitives/mac/cmac.rst +++ b/docs/hazmat/primitives/mac/cmac.rst @@ -10,8 +10,8 @@ Cipher-based message authentication code 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 +`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. @@ -38,9 +38,9 @@ A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`. :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be raised. - If the `algorithm`` isn't a - :class:`~cryptography.primitives.interfaces.BlockCipherAlgorithm` provider, - ``TypeError`` will be raised. + If ``algorithm`` isn't a + :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` + provider then ``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: @@ -68,6 +68,7 @@ A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`. :param bytes data: The bytes to hash and authenticate. :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + :raises TypeError: This exception is raised if ``data`` is not ``bytes``. .. method:: copy() @@ -89,6 +90,8 @@ A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`. :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` :raises cryptography.exceptions.InvalidSignature: If signature does not match digest + :raises TypeError: This exception is raised if ``signature`` is not + ``bytes``. .. method:: finalize() diff --git a/docs/hazmat/primitives/mac/hmac.rst b/docs/hazmat/primitives/mac/hmac.rst index 11b10735..d56927b9 100644 --- a/docs/hazmat/primitives/mac/hmac.rst +++ b/docs/hazmat/primitives/mac/hmac.rst @@ -38,6 +38,10 @@ of a message. :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be raised. + If ``algorithm`` isn't a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider + then ``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: @@ -65,6 +69,7 @@ of a message. :param bytes msg: The bytes to hash and authenticate. :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + :raises TypeError: This exception is raised if ``msg`` is not ``bytes``. .. method:: copy() @@ -86,6 +91,8 @@ of a message. :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` :raises cryptography.exceptions.InvalidSignature: If signature does not match digest + :raises TypeError: This exception is raised if ``signature`` is not + ``bytes``. .. method:: finalize() diff --git a/docs/hazmat/primitives/mac/index.rst b/docs/hazmat/primitives/mac/index.rst index 59fb8da2..acfe9bed 100644 --- a/docs/hazmat/primitives/mac/index.rst +++ b/docs/hazmat/primitives/mac/index.rst @@ -3,6 +3,14 @@ Message Authentication Codes ============================ +While cryptography supports both the CMAC and HMAC algorithms, we strongly +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?`_ + +.. _`Use cases for CMAC vs. HMAC?`: http://crypto.stackexchange.com/questions/15721/use-cases-for-cmac-vs-hmac + .. toctree:: :maxdepth: 1 |