diff options
Diffstat (limited to 'docs/hazmat/primitives')
| -rw-r--r-- | docs/hazmat/primitives/cryptographic-hashes.rst | 3 | ||||
| -rw-r--r-- | docs/hazmat/primitives/hmac.rst | 10 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 11 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 13 |
4 files changed, 36 insertions, 1 deletions
diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 90ca198a..38347378 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -28,6 +28,9 @@ Message Digests >>> digest.finalize() '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.UnsupportedAlgorithm` 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, become broken. Because of this it's important to include a plan for diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 0c0d0220..b8f94fd2 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -34,6 +34,8 @@ message. >>> h.finalize() '#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.UnsupportedAlgorithm` will be raised. :param key: Secret key as ``bytes``. :param algorithm: A @@ -69,3 +71,11 @@ message. :return bytes: The message digest as bytes. :raises cryptography.exceptions.AlreadyFinalized: + + .. method:: verify(signature) + + Finalize the current context and securely compare digest to ``signature``. + + :param bytes signature: The bytes of the HMAC signature recieved. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + :raises cryptography.exceptions.InvalidSignature: If signature does not match digest diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index e798c0e6..edb24cd9 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -36,6 +36,17 @@ Symmetric Ciphers The number of bits in the key being used. +.. class:: BlockCipherAlgorithm + + A block cipher algorithm. + + .. attribute:: block_size + + :type: int + + The number of bits in a block. + + Cipher Modes ------------ diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index f4d0457a..30896a05 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -61,7 +61,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. provider. If the backend doesn't support the requested combination of ``cipher`` - and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` + and ``mode`` an :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. .. method:: decryptor() @@ -352,6 +352,16 @@ Modes Do not reuse an ``initialization_vector`` with a given ``key``. + .. note:: + + Cryptography will emit a 128-bit tag when finalizing encryption. + You can shorten a tag by truncating it to the desired length, but this + is **not recommended** as it lowers the security margins of the + authentication (`NIST SP-800-38D`_ recommends 96-bits or greater). + If you must shorten the tag the minimum allowed length is 4 bytes + (32-bits). Applications **must** verify the tag is the expected length + to guarantee the expected security margin. + :param bytes tag: The tag bytes to verify during decryption. When encrypting this must be None. @@ -390,3 +400,4 @@ Insecure Modes .. _`described by Colin Percival`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html .. _`recommends 96-bit IV length`: http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf +.. _`NIST SP-800-38D`: http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf |