Update HMAC and Digest docs.
diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst
index 86b8585..627ca7b 100644
--- a/docs/hazmat/primitives/cryptographic-hashes.rst
+++ b/docs/hazmat/primitives/cryptographic-hashes.rst
@@ -29,7 +29,7 @@
'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90'
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.
Keep in mind that attacks against cryptographic hashes only get stronger
with time, and that often algorithms that were once thought to be strong,
@@ -47,26 +47,26 @@
.. method:: update(data)
- :param bytes data: The bytes you wish to hash.
- :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
+ :param bytes data: The bytes to be hashed.
+ :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`.
.. method:: copy()
- Copy this :class:`Hash` 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.
+ Copy this :class:`Hash` instance, usually so that you may call
+ :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:`Hash` that can be updated
- and finalized independently of the original instance.
- :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
+ and finalized independently of the original instance.
+ :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`.
.. method:: finalize()
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`, and :meth:`finalize` will raise an
+ :class:`~cryptography.exceptions.AlreadyFinalized` exception.
:return bytes: The message digest as bytes.
@@ -83,7 +83,7 @@
.. class:: SHA1()
- SHA-1 is a cryptographic hash function standardized by NIST. It has a
+ SHA-1 is a cryptographic hash function standardized by NIST. It produces an
160-bit message digest.
SHA-2 Family
@@ -91,23 +91,23 @@
.. class:: SHA224()
- SHA-224 is a cryptographic hash function from the SHA-2 family and
- standardized by NIST. It has a 224-bit message digest.
+ SHA-224 is a cryptographic hash function from the SHA-2 family and is
+ standardized by NIST. It produces a 224-bit message digest.
.. class:: SHA256()
- SHA-256 is a cryptographic hash function from the SHA-2 family and
- standardized by NIST. It has a 256-bit message digest.
+ SHA-256 is a cryptographic hash function from the SHA-2 family and is
+ standardized by NIST. It produces a 256-bit message digest.
.. class:: SHA384()
- SHA-384 is a cryptographic hash function from the SHA-2 family and
- standardized by NIST. It has a 384-bit message digest.
+ SHA-384 is a cryptographic hash function from the SHA-2 family and is
+ standardized by NIST. It produces a 384-bit message digest.
.. class:: SHA512()
- SHA-512 is a cryptographic hash function from the SHA-2 family and
- standardized by NIST. It has a 512-bit message digest.
+ SHA-512 is a cryptographic hash function from the SHA-2 family and is
+ standardized by NIST. It produces a 512-bit message digest.
RIPEMD160
~~~~~~~~~
@@ -115,7 +115,7 @@
.. class:: RIPEMD160()
RIPEMD160 is a cryptographic hash function that is part of ISO/IEC
- 10118-3:2004. It has a 160-bit message digest.
+ 10118-3:2004. It produces a 160-bit message digest.
Whirlpool
~~~~~~~~~
@@ -123,7 +123,7 @@
.. class:: Whirlpool()
Whirlpool is a cryptographic hash function that is part of ISO/IEC
- 10118-3:2004. It has a 512-bit message digest.
+ 10118-3:2004. It produces a 512-bit message digest.
MD5
~~~
@@ -136,8 +136,8 @@
.. class:: MD5()
- MD5 is a deprecated cryptographic hash function. It has a 128-bit message
- digest and has practical known collision attacks.
+ MD5 is a deprecated cryptographic hash function. It produces a 128-bit
+ message digest and has practical known collision attacks.
.. _`Lifetimes of cryptographic hash functions`: http://valerieaurora.org/hash.html
diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst
index 1a2838f..6ca9e16 100644
--- a/docs/hazmat/primitives/hmac.rst
+++ b/docs/hazmat/primitives/hmac.rst
@@ -12,13 +12,13 @@
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 @@
'#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 @@
...
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 <cryptographic-hash-algorithms>`.
- :param backend: A
+ :param backend: An
:class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
provider.
@@ -64,8 +64,8 @@
.. 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 @@
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: