From ab5f0116a2fc906b854b0593675492ec5e406a3d Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 8 Nov 2013 10:34:00 -0800 Subject: Be more and more explicit about how to do things correctly --- docs/hazmat/primitives/cryptographic-hashes.rst | 7 ++++--- docs/hazmat/primitives/symmetric-encryption.rst | 23 +++++++++++++++++------ 2 files changed, 21 insertions(+), 9 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 76ca20c0..20fa23cf 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -12,9 +12,9 @@ Message Digests results (with a high probability) in different digests. This is an implementation of - :class:`cryptography.hazmat.primitives.interfaces.HashContext` meant to + :class:`~cryptography.hazmat.primitives.interfaces.HashContext` meant to be used with - :class:`cryptography.hazmat.primitives.interfaces.HashAlgorithm` + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` implementations to provide an incremental interface to calculating various message digests. @@ -102,7 +102,8 @@ MD5 .. warning:: MD5 is a deprecated hash algorithm that has practical known collision - attacks. You are strongly discouraged from using it. + attacks. You are strongly discouraged from using it. Existing applications + should strongly consider moving away. .. class:: MD5() diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 5f1a64a1..5542e832 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -14,13 +14,22 @@ Symmetric Encryption Symmetric encryption is a way to encrypt (hide the plaintext value) material -where the encrypter and decrypter both use the same key. +where the encrypter and decrypter both use the same key. Note that symmetric +encryption is **not** sufficient for most applications, because it only +provides secrecy (an attacker can't see the message) but not authenticity (an +attacker can create bogus messages and force the application to decrypt them). +For this reason it is *strongly* reccomended to combine encryption with a +message authentication code, such as :doc:`HMAC `, in +an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. class:: Cipher(algorithm, mode) - Cipher objects combine an algorithm (such as AES) with a mode (such as - CBC, CTR, or GCM). A simple example of encrypting (and then decrypting) - content with AES is: + Cipher objects combine an algorithm (such as + :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`) with a + mode (such as + :class:`~cryptography.hazmat.primitives.ciphers.modes.CBC` or + :class:`~cryptography.hazmat.primitives.ciphers.modes.CTR`). A simple + example of encrypting (and then decrypting) content with AES is: .. doctest:: @@ -143,8 +152,7 @@ Weak Ciphers Blowfish is a block cipher developed by Bruce Schneier. It is known to be susceptible to attacks when using weak keys. The author has recommended - that users of Blowfish move to newer algorithms like - :class:`AES`. + that users of Blowfish move to newer algorithms, such as :class:`AES`. :param bytes key: The secret key, 32-448 bits in length (in increments of 8). This must be kept secret. @@ -252,3 +260,6 @@ Insecure Modes ciphers. Each block of data is encrypted in the same way. This means identical plaintext blocks will always result in identical ciphertext blocks, and thus result in information leakage + + +.. _`described by Colin Percival`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html -- cgit v1.2.3