Danger

This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns.

# Poly1305

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 cryptography.hazmat.primitives.poly1305.Poly1305(key)

  New in version 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 `ChaCha20Poly1305` instead.

      >>> 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 `verify()` method. You will receive an exception if the tag is wrong:

      >>> 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.

  Parameters

    key (bytes-like) – Secret key as `bytes`.

  Raises

    cryptography.exceptions.UnsupportedAlgorithm – This is raised if the version of OpenSSL `cryptography` is compiled against does not support this algorithm.

  update(data)
    Parameters

      data (bytes-like) – The bytes to hash and authenticate.

    Raises

      - cryptography.exceptions.AlreadyFinalized – See `finalize()`

      - TypeError – This exception is raised if `data` is not `bytes`.

  verify(tag)

    Finalize the current context and securely compare the MAC to `tag`.

    Parameters

      tag (bytes) – The bytes to compare against.

    Raises

      - cryptography.exceptions.AlreadyFinalized – See `finalize()`

      - cryptography.exceptions.InvalidSignature – If tag does not match.

      - TypeError – This exception is raised if `tag` is not `bytes`.

    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 `update()`, `verify()`, and `finalize()` will raise an `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`.

    Parameters

      - key (bytes-like) – Secret key as `bytes`.

      - data (bytes-like) – The bytes to hash and authenticate.

    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.

      - TypeError – This exception is raised if `key` or `data` are not `bytes`.

        >>> 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`.

    Parameters

      - key (bytes-like) – Secret key as `bytes`.

      - data (bytes-like) – The bytes to hash and authenticate.

      - tag (bytes) – 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.

      - TypeError – This exception is raised if `key`, `data` or `tag` are not `bytes`.

      - cryptography.exceptions.InvalidSignature – If tag does not match.

        >>> 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.