Merge branch 'master' into fernet

1 files changed, 46 insertions, 9 deletions

diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 5f1a64a1..eef359d6 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 sender and receiver 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* recommended 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::
 
@@ -70,6 +79,7 @@ where the encrypter and decrypter both use the same key.
 
         :param bytes data: The data you wish to pass into the context.
         :return bytes: Returns the data that was encrypted or decrypted.
+        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
 
         When the ``Cipher`` was constructed in a mode that turns it into a
         stream cipher (e.g.
@@ -81,6 +91,10 @@ where the encrypter and decrypter both use the same key.
 
         :return bytes: Returns the remainder of the data.
 
+        Once ``finalize`` is called this object can no longer be used and
+        :meth:`update` and :meth:`finalize` will raise
+        :class:`~cryptography.exceptions.AlreadyFinalized`.
+
 Algorithms
 ~~~~~~~~~~
 
@@ -107,10 +121,10 @@ Algorithms
 
 .. class:: TripleDES(key)
 
-    Triple DES (Data Encryption Standard), sometimes refered to as 3DES, is a
-    block cipher standardized by NIST. Triple DES has known cryptoanalytic
+    Triple DES (Data Encryption Standard), sometimes referred to as 3DES, is a
+    block cipher standardized by NIST. Triple DES has known crypto-analytic
     flaws, however none of them currently enable a practical attack.
-    Nonetheless, Triples DES is not reccomended for new applications because it
+    Nonetheless, Triples DES is not recommended for new applications because it
     is incredibly slow; old applications should consider moving away from it.
 
     :param bytes key: The secret key, either ``64``, ``128``, or ``192`` bits
@@ -143,12 +157,32 @@ 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.
 
+.. class:: ARC4(key)
+
+    ARC4 (Alleged RC4) is a stream cipher with serious weaknesses in its
+    initial stream output. Its use is strongly discouraged. ARC4 does not use
+    mode constructions.
+
+    :param bytes key: The secret key, ``40``, ``56``, ``64``, ``80``, ``128``,
+                      ``192``, or ``256`` bits in length.  This must be kept
+                      secret.
+
+    .. doctest::
+
+        >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+        >>> algorithm = algorithms.ARC4(key)
+        >>> cipher = Cipher(algorithm, mode=None)
+        >>> encryptor = cipher.encryptor()
+        >>> ct = encryptor.update(b"a secret message")
+        >>> decryptor = cipher.decryptor()
+        >>> decryptor.update(ct)
+        'a secret message'
+
 
 .. _symmetric-encryption-modes:
 
@@ -252,3 +286,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