diff options
Diffstat (limited to 'docs/hazmat/primitives/mac')
| -rw-r--r-- | docs/hazmat/primitives/mac/cmac.rst | 20 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/hmac.rst | 20 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/index.rst | 9 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/poly1305.rst | 132 |
4 files changed, 157 insertions, 24 deletions
diff --git a/docs/hazmat/primitives/mac/cmac.rst b/docs/hazmat/primitives/mac/cmac.rst index e04a849f..a5b13caf 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 @@ -22,7 +22,7 @@ A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`. .. versionadded:: 0.4 CMAC objects take a - :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm` provider. + :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm` instance. .. doctest:: @@ -32,7 +32,7 @@ A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`. >>> 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' + b'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 @@ -40,7 +40,7 @@ A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`. If ``algorithm`` isn't a :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm` - provider then ``TypeError`` will be raised. + instance 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: @@ -54,12 +54,10 @@ A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`. ... cryptography.exceptions.InvalidSignature: Signature did not match digest. - :param algorithm: An - :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm` - provider. - :param backend: An - :class:`~cryptography.hazmat.backends.interfaces.CMACBackend` - provider. + :param algorithm: An instance of + :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm`. + :param backend: An instance of + :class:`~cryptography.hazmat.backends.interfaces.CMACBackend`. :raises TypeError: This is raised if the provided ``algorithm`` is not an instance of :class:`~cryptography.hazmat.primitives.ciphers.BlockCipherAlgorithm` :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the diff --git a/docs/hazmat/primitives/mac/hmac.rst b/docs/hazmat/primitives/mac/hmac.rst index 2515ac91..9d11694b 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 @@ -18,7 +18,7 @@ of a message. .. class:: HMAC(key, algorithm, backend) HMAC objects take a ``key`` and a - :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` instance. The ``key`` should be :doc:`randomly generated bytes </random-numbers>` and is recommended to be equal in length to the ``digest_size`` of the hash function chosen. You must keep the ``key`` secret. @@ -32,14 +32,14 @@ of a message. >>> h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend()) >>> h.update(b"message to hash") >>> h.finalize() - '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J' + b'#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J' If the backend doesn't support the requested ``algorithm`` an :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be raised. If ``algorithm`` isn't a - :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` instance then ``TypeError`` will be raised. To check that a given signature is correct use the :meth:`verify` method. @@ -54,14 +54,15 @@ of a message. ... cryptography.exceptions.InvalidSignature: Signature did not match digest. - :param bytes key: Secret key as ``bytes``. + :param key: Secret key as ``bytes``. + :type key: :term:`bytes-like` :param algorithm: An :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` - provider such as those described in + instance such as those described in :ref:`Cryptographic Hashes <cryptographic-hash-algorithms>`. :param backend: An :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` - provider. + instance. :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the provided ``backend`` does not implement @@ -69,7 +70,8 @@ of a message. .. method:: update(msg) - :param bytes msg: The bytes to hash and authenticate. + :param msg: The bytes to hash and authenticate. + :type msg: :term:`bytes-like` :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` :raises TypeError: This exception is raised if ``msg`` is not ``bytes``. diff --git a/docs/hazmat/primitives/mac/index.rst b/docs/hazmat/primitives/mac/index.rst index bc54bae4..8bfe29e3 100644 --- a/docs/hazmat/primitives/mac/index.rst +++ b/docs/hazmat/primitives/mac/index.rst @@ -3,16 +3,17 @@ 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. +While cryptography supports multiple MAC algorithms, we strongly +recommend that HMAC should be used unless you have a very specific need. 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 cmac hmac + poly1305 + +.. _`Use cases for CMAC vs. HMAC?`: https://crypto.stackexchange.com/questions/15721/use-cases-for-cmac-vs-hmac diff --git a/docs/hazmat/primitives/mac/poly1305.rst b/docs/hazmat/primitives/mac/poly1305.rst new file mode 100644 index 00000000..7504a076 --- /dev/null +++ b/docs/hazmat/primitives/mac/poly1305.rst @@ -0,0 +1,132 @@ +.. hazmat:: + +Poly1305 +======== + +.. currentmodule:: cryptography.hazmat.primitives.poly1305 + +.. testsetup:: + + key = b"\x01" * 32 + +Poly1305 is an authenticator that takes a 32-byte key and a message and +produces a 16-byte tag. This tag is used to authenticate the message. Each key +**must** only be used once. Using the same key to generate tags for multiple +messages allows an attacker to forge tags. Poly1305 is described in +:rfc:`7539`. + +.. class:: Poly1305(key) + + .. versionadded:: 2.7 + + .. warning:: + + Using the same key to generate tags for multiple messages allows an + attacker to forge tags. Always generate a new key per message you want + to authenticate. If you are using this as a MAC for + symmetric encryption please use + :class:`~cryptography.hazmat.primitives.ciphers.aead.ChaCha20Poly1305` + instead. + + .. doctest:: + + >>> from cryptography.hazmat.primitives import poly1305 + >>> p = poly1305.Poly1305(key) + >>> p.update(b"message to authenticate") + >>> p.finalize() + b'T\xae\xff3\xbdW\xef\xd5r\x01\xe2n=\xb7\xd2h' + + To check that a given tag is correct use the :meth:`verify` method. + You will receive an exception if the tag is wrong: + + .. doctest:: + + >>> p = poly1305.Poly1305(key) + >>> p.update(b"message to authenticate") + >>> p.verify(b"an incorrect tag") + Traceback (most recent call last): + ... + cryptography.exceptions.InvalidSignature: Value did not match computed tag. + + :param key: Secret key as ``bytes``. + :type key: :term:`bytes-like` + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the version of OpenSSL ``cryptography`` is compiled against does not + support this algorithm. + + .. method:: update(data) + + :param data: The bytes to hash and authenticate. + :type data: :term:`bytes-like` + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + :raises TypeError: This exception is raised if ``data`` is not ``bytes``. + + .. method:: verify(tag) + + Finalize the current context and securely compare the MAC to + ``tag``. + + :param bytes tag: The bytes to compare against. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + :raises cryptography.exceptions.InvalidSignature: If tag does not + match. + :raises TypeError: This exception is raised if ``tag`` is not + ``bytes``. + + .. 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:`verify`, and :meth:`finalize` + will raise an :class:`~cryptography.exceptions.AlreadyFinalized` + exception. + + :return bytes: The message authentication code as bytes. + :raises cryptography.exceptions.AlreadyFinalized: + + .. classmethod:: generate_tag(key, data) + + A single step alternative to do sign operations. Returns the message + authentication code as ``bytes`` for the given ``key`` and ``data``. + + :param key: Secret key as ``bytes``. + :type key: :term:`bytes-like` + :param data: The bytes to hash and authenticate. + :type data: :term:`bytes-like` + :return bytes: The message authentication code as bytes. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the version of OpenSSL ``cryptography`` is compiled against does not + support this algorithm. + :raises TypeError: This exception is raised if ``key`` or ``data`` are + not ``bytes``. + + .. doctest:: + + >>> poly1305.Poly1305.generate_tag(key, b"message to authenticate") + b'T\xae\xff3\xbdW\xef\xd5r\x01\xe2n=\xb7\xd2h' + + .. classmethod:: verify_tag(key, data, tag) + + A single step alternative to do verify operations. Securely compares the + MAC to ``tag``, using the given ``key`` and ``data``. + + :param key: Secret key as ``bytes``. + :type key: :term:`bytes-like` + :param data: The bytes to hash and authenticate. + :type data: :term:`bytes-like` + :param bytes tag: The bytes to compare against. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the version of OpenSSL ``cryptography`` is compiled against does not + support this algorithm. + :raises TypeError: This exception is raised if ``key``, ``data`` or + ``tag`` are not ``bytes``. + :raises cryptography.exceptions.InvalidSignature: If tag does not match. + + .. doctest:: + + >>> poly1305.Poly1305.verify_tag(key, b"message to authenticate", b"an incorrect tag") + Traceback (most recent call last): + ... + cryptography.exceptions.InvalidSignature: Value did not match computed tag. |