poly1305.rst

Poly1305

cryptography.hazmat.primitives.poly1305

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

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 ~cryptography.hazmat.primitives.ciphers.aead.ChaCha20Poly1305 instead.

>>> from cryptography.hazmat.primitives import poly1305 >>> p = poly1305.Poly1305(key) >>> p.update(b"message to authenticate") >>> p.finalize() b'Txaexff3xbdWxefxd5rx01xe2n=xb7xd2h'

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.

param key

The secret key.

type key

bytes-like

raises cryptography.exceptions.UnsupportedAlgorithm

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

update(data)

param data

The bytes to hash and authenticate.

type data

bytes-like

raises cryptography.exceptions.AlreadyFinalized

See finalize

raises TypeError

This exception is raised if data is not bytes.

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 finalize

raises cryptography.exceptions.InvalidSignature

If tag does not match.

raises 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 ~cryptography.exceptions.AlreadyFinalized exception.

return bytes

The message authentication code as bytes.

raises cryptography.exceptions.AlreadyFinalized

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

bytes-like

param data

The bytes to hash and authenticate.

type data

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.

>>> poly1305.Poly1305.generate_tag(key, b"message to authenticate") b'Txaexff3xbdWxefxd5rx01xe2n=xb7xd2h'

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

bytes-like

param data

The bytes to hash and authenticate.

type data

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.

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