diff options
-rw-r--r-- | docs/hazmat/primitives/cryptographic-hashes.rst | 48 | ||||
-rw-r--r-- | docs/hazmat/primitives/hmac.rst | 27 |
2 files changed, 38 insertions, 37 deletions
diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 86b85852..627ca7bd 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -29,7 +29,7 @@ Message Digests '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 @@ Message Digests .. 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 @@ SHA-1 .. 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 @@ SHA-2 Family .. 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 @@ RIPEMD160 .. 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 @@ Whirlpool .. 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 @@ MD5 .. 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 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 <cryptographic-hash-algorithms>`. - :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: |