From 7904346de1c5e0847e5e2e13bb4427488c3ef14c Mon Sep 17 00:00:00 2001 From: Alex Stapleton Date: Sun, 9 Mar 2014 16:46:26 +0000 Subject: Update HMAC and Digest docs. --- docs/hazmat/primitives/hmac.rst | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) (limited to 'docs/hazmat/primitives/hmac.rst') diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 1a2838f7..6ca9e167 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -12,13 +12,13 @@ Hash-based Message Authentication Codes Hash-based message authentication codes (or HMACs) are a tool for calculating message authentication codes using a cryptographic hash function coupled with a -secret key. You can use an HMAC to verify integrity as well as authenticate a -message. +secret key. You can use an HMAC to verify both the integrity and authenticity +of a message. .. class:: HMAC(key, algorithm, backend) - HMAC objects take a ``key`` and a provider of - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`. + HMAC objects take a ``key`` and a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider. The ``key`` should be randomly generated bytes and is recommended to be equal in length to the ``digest_size`` of the hash function chosen. You must keep the ``key`` secret. @@ -35,7 +35,7 @@ message. '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J' If the backend doesn't support the requested ``algorithm`` an - :class:`~cryptography.exceptions.UnsupportedHash` will be raised. + :class:`~cryptography.exceptions.UnsupportedHash` exception will be raised. To check that a given signature is correct use the :meth:`verify` method. You will receive an exception if the signature is wrong: @@ -47,12 +47,12 @@ message. ... cryptography.exceptions.InvalidSignature: Signature did not match digest. - :param key: Secret key as ``bytes``. - :param algorithm: A + :param bytes key: Secret key as ``bytes``. + :param algorithm: An :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider such as those described in :ref:`Cryptographic Hashes `. - :param backend: A + :param backend: An :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. @@ -64,8 +64,8 @@ message. .. method:: copy() Copy this :class:`HMAC` instance, usually so that we may call - :meth:`finalize` and get an intermediate digest value while we continue - to call :meth:`update` on the original. + :meth:`finalize` to get an intermediate digest value while we continue + to call :meth:`update` on the original instance. :return: A new instance of :class:`HMAC` that can be updated and finalized independently of the original instance. @@ -86,9 +86,10 @@ message. Finalize the current context and return the message digest as bytes. - Once ``finalize`` is called this object can no longer be used and - :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise - :class:`~cryptography.exceptions.AlreadyFinalized`. + After ``finalize`` has been called this object can no longer be used + and :meth:`update`, :meth:`copy`, :meth:`verify` and :meth:`finalize` + will raise an :class:`~cryptography.exceptions.AlreadyFinalized` + exception. :return bytes: The message digest as bytes. :raises cryptography.exceptions.AlreadyFinalized: -- cgit v1.2.3