Merge branch 'master' into add-crt-coefficients

* master:
  Also clean up this syntax
  Fixed a missing word in the RSA docs
  Fix comments in padding.py to be accurate
  add versionadded to cast5
  A few style nits in the docs
  add CAST5 support to changelog
  Changed .... lines to ~~~~ and s/Gnu\/Linux/Linux/
  Pypy is not a real word either apparently.
  Added Pypy note and fixed libffi's "spelling"
  Added Debian mention, extra missing packages
  Added a docs section on Linux installation
  remove some extra linebreaks
  add cast5 docs
  Syntax highlight the go code. Be mad Rob Pike.
  add cbc, cfb, ofb support to CAST5 (aka CAST128) for openssl & cc
  re-add CAST5 ECB support (OpenSSL & CC backends). fixes #417
  Switch this to a warning block
  Be clear about HKDF's applicability for password storage

Conflicts:
	docs/hazmat/primitives/rsa.rst

6 files changed, 53 insertions, 13 deletions

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 4d459bd9..cd289b6e 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -18,6 +18,7 @@ Changelog
 * Added :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`.
 * Added :doc:`/hazmat/backends/multibackend`.
 * Set default random for the :doc:`/hazmat/backends/openssl` to the OS random engine.
+* Added :class:`~cryptography.hazmat.primitives.ciphers.algorithms.CAST5` (CAST-128) support.
 
 0.1 - 2014-01-08
 ~~~~~~~~~~~~~~~~
diff --git a/docs/development/custom-vectors/cast5.rst b/docs/development/custom-vectors/cast5.rst
index 7f1d72c1..09b3bdb1 100644
--- a/docs/development/custom-vectors/cast5.rst
+++ b/docs/development/custom-vectors/cast5.rst
@@ -23,5 +23,6 @@ Verification
 The following go code was used to verify the vectors.
 
 .. literalinclude:: /development/custom-vectors/cast5/verify_cast5.go
+    :language: go
 
 Download link: :download:`verify_cast5.go </development/custom-vectors/cast5/verify_cast5.go>`
diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst
index 1937c2ec..d8a0e241 100644
--- a/docs/hazmat/primitives/key-derivation-functions.rst
+++ b/docs/hazmat/primitives/key-derivation-functions.rst
@@ -129,6 +129,10 @@ Different KDFs are suitable for different tasks such as:
     `HKDF`_ (HMAC-based Extract-and-Expand Key Derivation Function) is suitable
     for deriving keys of a fixed size used for other cryptographic operations.
 
+    .. warning::
+
+        HKDF should not be used for password storage.
+
     .. doctest::
 
         >>> import os
diff --git a/docs/hazmat/primitives/rsa.rst b/docs/hazmat/primitives/rsa.rst
index 4925366a..e7ec4749 100644
--- a/docs/hazmat/primitives/rsa.rst
+++ b/docs/hazmat/primitives/rsa.rst
@@ -20,10 +20,10 @@ RSA
 
     .. warning::
         This method only checks a limited set of properties of its arguments.
-        Using an RSA that you do not trust or with incorrect parameters may
-        lead to insecure operation, crashes, and other undefined behavior. We
-        recommend that you only ever load private keys that were generated with
-        software you trust.
+        Using an RSA private key that you do not trust or with incorrect
+        parameters may lead to insecure operation, crashes, and other undefined
+        behavior. We recommend that you only ever load private keys that were
+        generated with software you trust.
 
 
     This class conforms to the
@@ -32,9 +32,10 @@ RSA
 
     :raises TypeError: This is raised when the arguments are not all integers.
 
-    :raises ValueError: This is raised when the values of `p`, `q`,
-                        `private_exponent`, `public_exponent` or `modulus` do
-                        not match the bounds specified in `RFC 3447`_.
+    :raises ValueError: This is raised when the values of ``p``, ``q``,
+                        ``private_exponent``, ``public_exponent``, or
+                        ``modulus`` do not match the bounds specified in
+                        :rfc:`3447`.
 
     .. classmethod:: generate(public_exponent, key_size, backend)
 
@@ -68,12 +69,11 @@ RSA
 
     :raises TypeError: This is raised when the arguments are not all integers.
 
-    :raises ValueError: This is raised when the values of `public_exponent` or
-                        `modulus` do not match the bounds specified in
-                        `RFC 3447`_.
+    :raises ValueError: This is raised when the values of ``public_exponent``
+                        or ``modulus`` do not match the bounds specified in
+                        :rfc:`3447`.
 
 .. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem)
 .. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography
-.. _`RFC 3447`: https://tools.ietf.org/html/rfc3447
 .. _`use 65537`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html
 .. _`at least 2048`: http://www.ecrypt.eu.org/documents/D.SPA.20.pdf
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 85d8e8e3..d91dde9d 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -99,7 +99,6 @@ Algorithms
     :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits.
                       This must be kept secret.
 
-
 .. class:: TripleDES(key)
 
     Triple DES (Data Encryption Standard), sometimes referred to as 3DES, is a
@@ -116,6 +115,17 @@ Algorithms
                       ``56`` bits long), they can simply be concatenated to
                       produce the full key. This must be kept secret.
 
+.. class:: CAST5(key)
+
+    .. versionadded:: 0.2
+
+    CAST5 (also known as CAST-128) is a block cipher approved for use in the
+    Canadian government by the `Communications Security Establishment`_. It is
+    a variable key length cipher and supports keys from 40-128 bits in length.
+
+    :param bytes key: The secret key, 40-128 bits in length (in increments of
+                      8).  This must be kept secret.
+
 Weak Ciphers
 ------------
 
@@ -469,3 +479,4 @@ Interfaces
 .. _`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
+.. _`Communications Security Establishment`: http://www.cse-cst.gc.ca
diff --git a/docs/installation.rst b/docs/installation.rst
index 7e7348e2..f9c3574d 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -22,8 +22,31 @@ to include the corresponding locations. For example:
     C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE%
     C:\> pip install cryptography
 
+Building cryptography on Linux
+------------------------------
+
+``cryptography`` should build very easily on Linux provided you have a C
+compiler, headers for Python (if you're not using ``pypy``), and headers for
+the OpenSSL and ``libffi`` libraries available on your system.
+
+Debian and Ubuntu systems
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For Debian and Ubuntu, the following command line will ensure the required
+dependencies are installed:
+
+.. code-block:: console
+
+    $ sudo apt-get install build-essential libssl-dev libffi-dev python-dev
+
+You should now be able to build and install cryptography with the usual
+
+.. code-block:: console
+
+    $ pip install cryptography
+
 Using your own OpenSSL on Linux
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Python links to OpenSSL for its own purposes and this can sometimes cause
 problems when you wish to use a different version of OpenSSL with cryptography.