aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorPaul Kehrer <paul.l.kehrer@gmail.com>2019-03-10 10:12:00 +0800
committerAlex Gaynor <alex.gaynor@gmail.com>2019-03-09 21:12:00 -0500
commitb73ed5a6a3067c832413a6b4c987667a9d545153 (patch)
treee8d2881b29c41bc7967c2e24805de506fc996468 /docs
parent3a300e6c8ed64503f3ef6cc22e5dda403fe8751a (diff)
downloadcryptography-b73ed5a6a3067c832413a6b4c987667a9d545153.tar.gz
cryptography-b73ed5a6a3067c832413a6b4c987667a9d545153.tar.bz2
cryptography-b73ed5a6a3067c832413a6b4c987667a9d545153.zip
poly1305 support (#4802)
* poly1305 support * some more tests * have I mentioned how bad the spellchecker is? * doc improvements * EVP_PKEY_new_raw_private_key copies the key but that's not documented Let's assume that might change and be very defensive * review feedback * add a test that fails on a tag of the correct length but wrong value * docs improvements
Diffstat (limited to 'docs')
-rw-r--r--docs/hazmat/primitives/mac/index.rst1
-rw-r--r--docs/hazmat/primitives/mac/poly1305.rst87
-rw-r--r--docs/spelling_wordlist.txt2
3 files changed, 90 insertions, 0 deletions
diff --git a/docs/hazmat/primitives/mac/index.rst b/docs/hazmat/primitives/mac/index.rst
index f85eaa0e..8bfe29e3 100644
--- a/docs/hazmat/primitives/mac/index.rst
+++ b/docs/hazmat/primitives/mac/index.rst
@@ -14,5 +14,6 @@ HMAC?`_
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..1d0753c6
--- /dev/null
+++ b/docs/hazmat/primitives/mac/poly1305.rst
@@ -0,0 +1,87 @@
+.. 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:
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index c9b4777e..47d37301 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -1,6 +1,7 @@
accessor
affine
Authenticator
+authenticator
backend
Backends
backends
@@ -77,6 +78,7 @@ Parallelization
personalization
pickleable
plaintext
+Poly
pre
precompute
preprocessor