iCE40/yosys - clone of https://github.com/YosysHQ/yosys

about summary refs log tree commit diff stats

path: root/misc/yosysjs/yosyswrk.js

	Commit message (Expand)	Author	Age	Files	Lines
*	Improved YosysJS WebWorker API	Clifford Wolf	2015-07-04	1	-2/+22
*	Added YosysJS.create_worker()	Clifford Wolf	2015-06-28	1	-0/+43

a id='n11' href='#n11'>11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 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.