← Back
Editing: poly1305.rst
.. 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: The secret key. :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.
Save File
Cancel