Merge branch 'master' into fernet

10 files changed, 163 insertions, 21 deletions

diff --git a/docs/community.rst b/docs/community.rst
index 552318da..bf1cd1c7 100644
--- a/docs/community.rst
+++ b/docs/community.rst
@@ -9,7 +9,12 @@ You can find ``cryptography`` all over the web:
 * `Documentation`_
 * IRC: ``#cryptography-dev`` on ``irc.freenode.net``
 
+Wherever we interact, we strive to follow the `Python Community Code of
+Conduct`_.
+
+
 .. _`Mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev
 .. _`Source code`: https://github.com/pyca/cryptography
 .. _`Issue tracker`: https://github.com/pyca/cryptography/issues
 .. _`Documentation`: https://cryptography.io/
+.. _`Python Community Code of Conduct`: http://www.python.org/psf/codeofconduct/
diff --git a/docs/conf.py b/docs/conf.py
index 8e0fc7be..69be32e9 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -252,7 +252,3 @@ texinfo_documents = [
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
-
-
-# Enable the new ReadTheDocs theme
-RTD_NEW_THEME = True
diff --git a/docs/contributing.rst b/docs/contributing.rst
index e1475b88..3b301842 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -206,4 +206,4 @@ The HTML documentation index can now be found at ``docs/_build/html/index.html``
 .. _`virtualenv`: https://pypi.python.org/pypi/virtualenv
 .. _`pip`: https://pypi.python.org/pypi/pip
 .. _`sphinx`: https://pypi.python.org/pypi/sphinx
-.. _`reStructured Text`: http://docutils.sourceforge.net/rst.html
+.. _`reStructured Text`: http://sphinx-doc.org/rest.html
diff --git a/docs/exceptions.rst b/docs/exceptions.rst
new file mode 100644
index 00000000..6ac11b3c
--- /dev/null
+++ b/docs/exceptions.rst
@@ -0,0 +1,9 @@
+Exceptions
+==========
+
+.. currentmodule:: cryptography.exceptions
+
+.. class:: UnsupportedAlgorithm
+
+    This is raised when a backend doesn't support the requested algorithm (or
+    combination of algorithms).
diff --git a/docs/glossary.rst b/docs/glossary.rst
new file mode 100644
index 00000000..e4fc8283
--- /dev/null
+++ b/docs/glossary.rst
@@ -0,0 +1,30 @@
+Glossary
+========
+
+.. glossary::
+
+    plaintext
+        User-readable data you care about.
+
+    ciphertext
+        The encoded data, it's not user readable. Potential attackers are able
+        to see this.
+
+    encryption
+        The process of converting plaintext to ciphertext.
+
+    decryption
+        The process of converting ciphertext to plaintext.
+
+    key
+        Secret data is encoded with a function using this key. Sometimes
+        multiple keys are used. These **must** be kept secret, if a key is
+        exposed to an attacker, any data encrypted with it will be exposed.
+
+    symmetric cryptography
+        Cryptographic operations where encryption and decryption use the same
+        key.
+
+    asymmetric cryptography
+        Cryptographic operations where encryption and decryption use different
+        keys. There are seperate encryption and decryption keys.
diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst
index 301d72d5..bd1a4934 100644
--- a/docs/hazmat/primitives/hmac.rst
+++ b/docs/hazmat/primitives/hmac.rst
@@ -23,6 +23,8 @@ message.
     equal in length to the ``digest_size`` of the hash function chosen.
     You must keep the ``key`` secret.
 
+    This is an implementation of :rfc:`2104`.
+
     .. doctest::
 
         >>> from cryptography.hazmat.primitives import hashes, hmac
diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst
index c81018ae..614c414a 100644
--- a/docs/hazmat/primitives/index.rst
+++ b/docs/hazmat/primitives/index.rst
@@ -10,3 +10,4 @@ Primitives
     hmac
     symmetric-encryption
     padding
+    interfaces
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
new file mode 100644
index 00000000..7068316e
--- /dev/null
+++ b/docs/hazmat/primitives/interfaces.rst
@@ -0,0 +1,59 @@
+.. hazmat::
+
+Interfaces
+==========
+
+
+``cryptography`` uses `Abstract Base Classes`_ as interfaces to describe the
+properties and methods of most primitive constructs. Backends may also use
+this information to influence their operation. Interfaces should also be used
+to document argument and return types.
+
+.. _`Abstract Base Classes`: http://docs.python.org/3.2/library/abc.html
+
+
+Cipher Modes
+~~~~~~~~~~~~
+
+.. currentmodule:: cryptography.hazmat.primitives.interfaces
+
+Interfaces used by the symmetric cipher modes described in
+:ref:`Symmetric Encryption Modes <symmetric-encryption-modes>`.
+
+.. class:: Mode
+
+    A named cipher mode.
+
+    .. attribute:: name
+
+        :type: str
+
+        This should be the standard shorthand name for the mode, for example
+        Cipher-Block Chaining mode is "CBC".
+
+        The name may be used by a backend to influence the operation of a
+        cipher in conjunction with the algorithm's name.
+
+
+.. class:: ModeWithInitializationVector
+
+    A cipher mode with an initialization vector.
+
+    .. attribute:: initialization_vector
+
+        :type: bytes
+
+        Exact requirements of the initialization are described by the
+        documentation of individual modes.
+
+
+.. class:: ModeWithNonce
+
+    A cipher mode with a nonce.
+
+    .. attribute:: nonce
+
+        :type: bytes
+
+        Exact requirements of the nonce are described by the documentation of
+        individual modes.
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 5852dc21..5f1a64a1 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -4,7 +4,7 @@
 Symmetric Encryption
 ====================
 
-.. currentmodule:: cryptography.hazmat.primitives.block
+.. currentmodule:: cryptography.hazmat.primitives.ciphers
 
 .. testsetup::
 
@@ -16,24 +16,23 @@ Symmetric Encryption
 Symmetric encryption is a way to encrypt (hide the plaintext value) material
 where the encrypter and decrypter both use the same key.
 
-.. class:: BlockCipher(cipher, mode)
+.. class:: Cipher(algorithm, mode)
 
-    Block ciphers work by encrypting content in chunks, often 64- or 128-bits.
-    They combine an underlying algorithm (such as AES), with a mode (such as
+    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:
 
     .. doctest::
 
-        >>> from cryptography.hazmat.primitives.block import BlockCipher, ciphers, modes
-        >>> cipher = BlockCipher(ciphers.AES(key), modes.CBC(iv))
+        >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+        >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv))
         >>> encryptor = cipher.encryptor()
         >>> ct = encryptor.update(b"a secret message") + encryptor.finalize()
         >>> decryptor = cipher.decryptor()
         >>> decryptor.update(ct) + decryptor.finalize()
         'a secret message'
 
-    :param cipher: One of the ciphers described below.
+    :param algorithms: One of the algorithms described below.
     :param mode: One of the modes described below.
 
     .. method:: encryptor()
@@ -42,17 +41,26 @@ where the encrypter and decrypter both use the same key.
             :class:`~cryptography.hazmat.primitives.interfaces.CipherContext`
             provider.
 
+        If the backend doesn't support the requested combination of ``cipher``
+        and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm`
+        will be raised.
+
     .. method:: decryptor()
 
         :return: A decrypting
             :class:`~cryptography.hazmat.primitives.interfaces.CipherContext`
             provider.
 
+        If the backend doesn't support the requested combination of ``cipher``
+        and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm`
+        will be raised.
+
+
 .. currentmodule:: cryptography.hazmat.primitives.interfaces
 
 .. class:: CipherContext
 
-    When calling ``encryptor()`` or ``decryptor()`` on a ``BlockCipher`` object
+    When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object
     you will receive a return object conforming to the ``CipherContext``
     interface. You can then call ``update(data)`` with data until you have fed
     everything into the context. Once that is done call ``finalize()`` to
@@ -63,14 +71,20 @@ 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.
 
+        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,
+        whose size is determined by the cipher's block size.
+
     .. method:: finalize()
 
         :return bytes: Returns the remainder of the data.
 
-Ciphers
-~~~~~~~
+Algorithms
+~~~~~~~~~~
 
-.. currentmodule:: cryptography.hazmat.primitives.block.ciphers
+.. currentmodule:: cryptography.hazmat.primitives.ciphers.algorithms
 
 .. class:: AES(key)
 
@@ -135,10 +149,13 @@ Weak Ciphers
     :param bytes key: The secret key, 32-448 bits in length (in increments of
                       8).  This must be kept secret.
 
+
+.. _symmetric-encryption-modes:
+
 Modes
 ~~~~~
 
-.. currentmodule:: cryptography.hazmat.primitives.block.modes
+.. currentmodule:: cryptography.hazmat.primitives.ciphers.modes
 
 .. class:: CBC(initialization_vector)
 
@@ -149,9 +166,29 @@ Modes
                                         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``.
+                                        ``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``.
+
+    A good construction looks like:
+
+    .. code-block:: pycon
+
+        >>> import os
+        >>> iv = os.urandom(16)
+        >>> mode = CBC(iv)
+
+    While the following is bad and will leak information:
+
+    .. code-block:: pycon
+
+        >>> iv = "a" * 16
+        >>> mode = CBC(iv)
 
 
 .. class:: CTR(nonce)
@@ -162,7 +199,8 @@ Modes
         block size of less than 128-bits.
 
     CTR (Counter) is a mode of operation for block ciphers. It is considered
-    cryptographically strong.
+    cryptographically strong. It transforms a block cipher into a stream
+    cipher.
 
     :param bytes nonce: Should be random bytes. It is critical to never reuse a
                         ``nonce`` with a given key.  Any reuse of a nonce
diff --git a/docs/index.rst b/docs/index.rst
index b9c5b5fb..b9bf1735 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -32,6 +32,8 @@ Contents
 
     fernet
     architecture
+    exceptions
+    glossary
     contributing
     security
     community