Merge branch 'master' into padding-fixes

Conflicts:
	cryptography/hazmat/primitives/padding.py

6 files changed, 38 insertions, 15 deletions

diff --git a/AUTHORS.rst b/AUTHORS.rst
index b3b7f35d..0ef9958d 100644
--- a/AUTHORS.rst
+++ b/AUTHORS.rst
@@ -10,4 +10,3 @@ PGP key fingerprints are enclosed in parentheses.
 * Christian Heimes <christian@python.org>
 * Paul Kehrer <paul.l.kehrer@gmail.com>
 * Jarret Raim <jarito@gmail.com>
-
diff --git a/dev-requirements.txt b/dev-requirements.txt
index 752517dd..cd975d5c 100644
--- a/dev-requirements.txt
+++ b/dev-requirements.txt
@@ -4,3 +4,5 @@ pytest
 coverage
 sphinx
 tox
+sphinx_rtd_theme
+-e .
diff --git a/docs/conf.py b/docs/conf.py
index 69be32e9..77050e72 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -14,6 +14,12 @@
 import os
 import sys
 
+try:
+    import sphinx_rtd_theme
+except ImportError:
+    sphinx_rtd_theme = None
+
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -98,16 +104,18 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+
+if sphinx_rtd_theme:
+    html_theme = "sphinx_rtd_theme"
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+else:
+    html_theme = "default"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #html_theme_options = {}
 
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
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 </hazmat/primitives/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
diff --git a/tox.ini b/tox.ini
index dab22a6d..257275ce 100644
--- a/tox.ini
+++ b/tox.ini
@@ -11,7 +11,9 @@ commands =
     coverage report -m
 
 [testenv:docs]
-deps = sphinx
+deps =
+    sphinx
+    sphinx_rtd_theme
 basepython = python2.7
 commands =
     sphinx-build -W -b html -d {envtmpdir}/doctrees docs docs/_build/html