Various "improvements" to the symmetric docs

1 files changed, 86 insertions, 80 deletions

diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 2bc25c50..2ee5085b 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -13,23 +13,25 @@ Symmetric Encryption
     iv = binascii.unhexlify(b"0" * 32)
 
 
-Symmetric encryption is a way to encrypt (hide the plaintext value) material
-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).
+Symmetric encryption is a way to `encrypt`_ or hide the contents of material
+where the sender and receiver both use the same secret key. Note that symmetric
+encryption is **not** sufficient for most applications because it only
+provides secrecy but not authenticity. That means an attacker can't see the
+message but 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, backend)
 
-    Cipher objects combine an algorithm (such as
-    :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`) with a
-    mode (such as
+    Cipher objects combine an algorithm such as
+    :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` with a
+    mode like
     :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:
+    :class:`~cryptography.hazmat.primitives.ciphers.modes.CTR`. A simple
+    example of encrypting and then decrypting content with AES is:
 
     .. doctest::
 
@@ -62,7 +64,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_.
 
         If the backend doesn't support the requested combination of ``cipher``
         and ``mode`` an :class:`~cryptography.exceptions.UnsupportedCipher`
-        will be raised.
+        exception will be raised.
 
     .. method:: decryptor()
 
@@ -72,7 +74,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_.
 
         If the backend doesn't support the requested combination of ``cipher``
         and ``mode`` an :class:`cryptography.exceptions.UnsupportedCipher`
-        will be raised.
+        exception will be raised.
 
 .. _symmetric-encryption-algorithms:
 
@@ -87,17 +89,17 @@ Algorithms
     AES is both fast, and cryptographically strong. It is a good default
     choice for encryption.
 
-    :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits.
-        This must be kept secret.
+    :param bytes key: The secret key. This must be kept secret. Either ``128``,
+        ``192``, or ``256`` bits long.
 
 .. class:: Camellia(key)
 
-    Camellia is a block cipher approved for use by CRYPTREC and ISO/IEC.
-    It is considered to have comparable security and performance to AES, but
+    Camellia is a block cipher approved for use by `CRYPTREC`_ and ISO/IEC.
+    It is considered to have comparable security and performance to AES but
     is not as widely studied or deployed.
 
-    :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits.
-        This must be kept secret.
+    :param bytes key: The secret key. This must be kept secret. Either ``128``,
+        ``192``, or ``256`` bits long.
 
 .. class:: TripleDES(key)
 
@@ -107,12 +109,11 @@ Algorithms
     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
-        (note that DES functionally uses ``56``, ``112``, or ``168`` bits of
-        the key, there is a parity byte in each component of the key), in some
-        materials these are referred to as being up to three separate keys
-        (each ``56`` bits long), they can simply be concatenated to produce the
-        full key. This must be kept secret.
+    :param bytes key: The secret key. This must be kept secret. Either ``64``,
+        ``128``, or ``192`` bits long. DES only uses ``56``, ``112``, or ``168``
+        bits of the key as there is a parity byte in each component of the key.
+        Some writing refers to there being up to three separate keys that are each
+        ``56`` bits long, they can simply be concatenated to produce the full key.
 
 .. class:: CAST5(key)
 
@@ -122,8 +123,8 @@ Algorithms
     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.
+    :param bytes key: The secret key, This must be kept secret. 40 to 128 bits
+        in length in increments of 8 bits.
 
 Weak Ciphers
 ------------
@@ -138,10 +139,10 @@ 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, such as :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.
+    :param bytes key: The secret key. This must be kept secret. 32 to 448 bits
+        in length in increments of 8 bits.
 
 .. class:: ARC4(key)
 
@@ -149,8 +150,8 @@ Weak Ciphers
     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.
+    :param bytes key: The secret key. This must be kept secret. Either ``40``,
+        ``56``, ``64``, ``80``, ``128``, ``192``, or ``256`` bits in length.
 
     .. doctest::
 
@@ -174,16 +175,16 @@ Modes
 
 .. class:: CBC(initialization_vector)
 
-    CBC (Cipher block chaining) is a mode of operation for block ciphers. It is
+    CBC (Cipher Block Chaining) is a mode of operation for block ciphers. It is
     considered cryptographically strong.
 
     **Padding is required when using this mode.**
 
     :param bytes initialization_vector: Must be random bytes. They do not need
-        to be kept secret (they can be included in a transmitted message). Must
-        be the same number of bytes as the ``block_size`` of the cipher. Each
-        time something is encrypted a new ``initialization_vector`` should be
-        generated. Do not reuse an ``initialization_vector`` with a given
+        to be kept secret and they can be included in a transmitted message.
+        Must be the same number of bytes as the ``block_size`` of the cipher.
+        Each time something is encrypted a new ``initialization_vector`` should
+        be generated. Do not reuse an ``initialization_vector`` with a given
         ``key``, and particularly do not use a constant
         ``initialization_vector``.
 
@@ -223,7 +224,7 @@ Modes
         compromises the security of every message encrypted with that key. Must
         be the same number of bytes as the ``block_size`` of the cipher with a
         given key. The nonce does not need to be kept secret and may be
-        included alongside the ciphertext.
+        included with the ciphertext.
 
 .. class:: OFB(initialization_vector)
 
@@ -233,9 +234,9 @@ Modes
     **This mode does not require padding.**
 
     :param bytes initialization_vector: Must be random bytes. They do not need
-        to be kept secret (they can be included in a transmitted message). Must
-        be the same number of bytes as the ``block_size`` of the cipher. Do not
-        reuse an ``initialization_vector`` with a given ``key``.
+        to be kept secret and they can be included in a transmitted message.
+        Must be the same number of bytes as the ``block_size`` of the cipher.
+        Do not reuse an ``initialization_vector`` with a given ``key``.
 
 .. class:: CFB(initialization_vector)
 
@@ -245,38 +246,38 @@ Modes
     **This mode does not require padding.**
 
     :param bytes initialization_vector: Must be random bytes. They do not need
-        to be kept secret (they can be included in a transmitted message). Must
-        be the same number of bytes as the ``block_size`` of the cipher. Do not
-        reuse an ``initialization_vector`` with a given ``key``.
+        to be kept secret and they can be included in a transmitted message.
+        Must be the same number of bytes as the ``block_size`` of the cipher.
+        Do not reuse an ``initialization_vector`` with a given ``key``.
 
 .. class:: GCM(initialization_vector, tag=None)
 
     .. danger::
 
-        When using this mode you MUST not use the decrypted data until
+        When using this mode you **must** not use the decrypted data until
         :meth:`~cryptography.hazmat.primitives.interfaces.CipherContext.finalize`
-        has been called. GCM provides NO guarantees of ciphertext integrity
+        has been called. GCM provides **no** guarantees of ciphertext integrity
         until decryption is complete.
 
     GCM (Galois Counter Mode) is a mode of operation for block ciphers. An
     AEAD (authenticated encryption with additional data) mode is a type of
-    block cipher mode that encrypts the message as well as authenticating it
-    (and optionally additional data that is not encrypted) simultaneously.
-    Additional means of verifying integrity (like
-    :doc:`HMAC </hazmat/primitives/hmac>`) are not necessary.
+    block cipher mode that simultaneously encrypts the message as well as
+    authenticating it. Additional unencrypted data may also be authenticated.
+    Additional means of verifying integrity such as
+    :doc:`HMAC </hazmat/primitives/hmac>` are not necessary.
 
     **This mode does not require padding.**
 
     :param bytes initialization_vector: Must be random bytes. They do not need
-        to be kept secret (they can be included in a transmitted message). NIST
-        `recommends 96-bit IV length`_ for performance critical situations, but
-        it can be up to 2\ :sup:`64` - 1 bits. Do not reuse an
+        to be kept secret and they can be included in a transmitted message.
+        NIST `recommends a 96-bit IV length`_ for performance critical
+        situations but it can be up to 2\ :sup:`64` - 1 bits. 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
+        Cryptography will generate 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
@@ -298,8 +299,8 @@ Modes
             # Generate a random 96-bit IV.
             iv = os.urandom(12)
 
-            # Construct a AES-GCM Cipher object with the given and our randomly
-            # generated IV.
+            # Construct a AES-GCM Cipher object with the given key and a
+            # randomly generated IV.
             encryptor = Cipher(
                 algorithms.AES(key),
                 modes.GCM(iv),
@@ -371,7 +372,7 @@ Insecure Modes
     ECB (Electronic Code Book) is the simplest mode of operation for block
     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
+    blocks, which can leave `significant patterns in the output`_.
 
     **Padding is required when using this mode.**
 
@@ -386,12 +387,13 @@ Interfaces
     context. Once that is done call ``finalize()`` to finish the operation and
     obtain the remainder of the data.
 
-    Block ciphers require that plaintext or ciphertext always be a multiple of
-    their block size, because of that **padding** is sometimes required to make
-    a message the correct size. ``CipherContext`` will not automatically apply
-    any padding; you'll need to add your own. For block ciphers the recommended
-    padding is :class:`cryptography.hazmat.primitives.padding.PKCS7`. If you
-    are using a stream cipher mode (such as
+    Block ciphers require that the plaintext or ciphertext always be a multiple
+    of their block size. Because of that **padding** is sometimes required to
+    make a message the correct size. ``CipherContext`` will not automatically
+    apply any padding; you'll need to add your own. For block ciphers the
+    recommended padding is
+    :class:`cryptography.hazmat.primitives.padding.PKCS7`. If you are using a
+    stream cipher mode (such as
     :class:`cryptography.hazmat.primitives.modes.CTR`) you don't have to worry
     about this.
 
@@ -404,31 +406,31 @@ Interfaces
         When the ``Cipher`` was constructed in a mode that turns it into a
         stream cipher (e.g.
         :class:`cryptography.hazmat.primitives.ciphers.modes.CTR`), this will
-        return bytes immediately, however in other modes it will return chunks,
+        return bytes immediately, however in other modes it will return chunks
         whose size is determined by the cipher's block size.
 
     .. method:: finalize()
 
         :return bytes: Returns the remainder of the data.
         :raises ValueError: This is raised when the data provided isn't
-            correctly padded to be a multiple of the algorithm's block size.
+            a multiple of the algorithm's block size.
 
         Once ``finalize`` is called this object can no longer be used and
-        :meth:`update` and :meth:`finalize` will raise
-        :class:`~cryptography.exceptions.AlreadyFinalized`.
+        :meth:`update` and :meth:`finalize` will raise an
+        :class:`~cryptography.exceptions.AlreadyFinalized` exception.
 
 .. class:: AEADCipherContext
 
-    When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object
+    When calling ``encryptor`` or ``decryptor`` on a ``Cipher`` object
     with an AEAD mode (e.g.
     :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) the result will
     conform to the ``AEADCipherContext`` and ``CipherContext`` interfaces. If
     it is an encryption context it will additionally be an
-    ``AEADEncryptionContext`` interface. ``AEADCipherContext`` contains an
-    additional method ``authenticate_additional_data`` for adding additional
-    authenticated but unencrypted data (see note below). You should call this
-    before calls to ``update``. When you are done call ``finalize()`` to finish
-    the operation.
+    ``AEADEncryptionContext`` provider. ``AEADCipherContext`` contains an
+    additional method :meth:`authenticate_additional_data` for adding
+    additional authenticated but unencrypted data (see note below). You should
+    call this before calls to ``update``. When you are done call `finalize``
+    to finish the operation.
 
     .. note::
 
@@ -444,12 +446,13 @@ Interfaces
 
 .. class:: AEADEncryptionContext
 
-    When creating an encryption context using ``encryptor()`` on a ``Cipher``
-    object with an AEAD mode (e.g.
-    :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) you will receive
-    a return object conforming to the ``AEADEncryptionContext`` interface (as
-    well as ``AEADCipherContext``).  This interface provides one additional
-    attribute ``tag``. ``tag`` can only be obtained after ``finalize()``.
+    When creating an encryption context using ``encryptor`` on a ``Cipher``
+    object with an AEAD mode such as
+    :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM` an object
+    conforming to both the ``AEADEncryptionContext`` and ``AEADCipherContext``
+    interfaces will be returned.  This interface provides one
+    additional attribute ``tag``. ``tag`` can only be obtained after
+    ``finalize`` has been called.
 
     .. attribute:: tag
 
@@ -459,6 +462,9 @@ 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
+.. _`recommends a 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
+.. _`encrypt`: https://ssd.eff.org/tech/encryption
+.. _`CRYPTREC`: http://www.cryptrec.go.jp/english/
+.. _`significant patterns in the output`: http://en.wikipedia.org/wiki/Cipher_block_chaining#Electronic_codebook_.28ECB.29