Merge branch 'master' into fernet

11 files changed, 158 insertions, 30 deletions

diff --git a/docs/api-stability.rst b/docs/api-stability.rst
new file mode 100644
index 00000000..e87cc140
--- /dev/null
+++ b/docs/api-stability.rst
@@ -0,0 +1,51 @@
+API Stability
+=============
+
+From its first release, ``cryptography`` will have a strong API stability
+policy.
+
+What does this policy cover?
+----------------------------
+
+This policy includes any API or behavior which is documented in this
+documentation.
+
+What does "stable" mean?
+------------------------
+
+* Public APIs will not be removed or renamed without providing a compatibility
+  alias.
+* The behavior of existing APIs will not change.
+
+What doesn't this policy cover?
+-------------------------------
+
+* We may add new features, things like the result of ``dir(obj))`` or the
+  contents of ``obj.__dict__`` may change.
+* Objects are not guaranteed to be pickleable, and pickled objects from one
+  version of ``cryptography`` may not be loadable in future versions.
+* Development versions of ``cryptography``. Before a feature is in a release,
+  it is not covered by this policy and may change.
+
+Security
+~~~~~~~~
+
+One exception to our API stability policy is for security. We will violate this
+policy as necessary in order to resolve a security issue or harden
+``cryptography`` against a possible attack.
+
+Deprecation
+-----------
+
+From time to time we will want to change the behavior of an API or remove it
+entirely. In that case, here's how the process will work:
+
+* In ``cryptography X.Y`` the feature exists.
+* In ``cryptography X.Y+1`` using that feature will emit a
+  ``PendingDeprecationWarning``.
+* In ``cryptography X.Y+2`` using that feature will emit a
+  ``DeprecationWarning``.
+* In ``cryptography X.Y+3`` the feature will be removed or changed.
+
+In short, code which runs without warnings will always continue to work for a
+period of two releases.
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 036043f5..620e1b6a 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -53,11 +53,10 @@ API Considerations
 
 Most projects' APIs are designed with a philosophy of "make easy things easy,
 and make hard things possible". One of the perils of writing cryptographic code
-is that code that is secure looks just like code that isn't, and produces
-results that are also difficult to distinguish. As a result ``cryptography``
-has, as a design philosophy: "make it hard to do insecure things". Here are a
-few strategies for API design which should be both followed, and should inspire
-other API choices:
+is that secure code looks just like insecure code, and its results are almost
+always indistinguishable. As a result ``cryptography`` has, as a design
+philosophy: "make it hard to do insecure things". Here are a few strategies for
+API design which should be both followed, and should inspire other API choices:
 
 If it is incorrect to ignore the result of a method, it should raise an
 exception, and not return a boolean ``True``/``False`` flag. For example, a
@@ -77,6 +76,10 @@ whether the signature was valid.
         if not is_valid:
             raise InvalidSignature
 
+Every recipe should include a version or algorithmic marker of some sort in its
+output in order to allow transparent upgrading of the algorithms in use, as
+the algorithms or parameters needed to achieve a given security margin evolve.
+
 APIs at the :doc:`/hazmat/primitives/index` layer should always take an
 explicit backend, APIs at the recipes layer should automatically use the
 :func:`~cryptography.hazmat.backends.default_backend`, but optionally allow
@@ -133,7 +136,6 @@ Include a space after commas between parameters:
     // Bad
     long f(int,char *)
 
-
 Documentation
 -------------
 
@@ -163,7 +165,7 @@ as much as possible. To that end:
 
 * When documenting a generic interface, use a strong algorithm in examples.
   (e.g. when showing a hashing example, don't use
-  :class:`cryptography.hazmat.primitives.hashes.MD5`)
+  :class:`~cryptography.hazmat.primitives.hashes.MD5`)
 * When giving prescriptive advice, always provide references and supporting
   material.
 * When there is real disagreement between cryptographic experts, represent both
@@ -206,7 +208,7 @@ automatically, so all you have to do is:
 
    $ py.test
    ...
-   4294 passed in 15.24 seconds
+   62746 passed in 220.43 seconds
 
 This runs the tests with the default Python interpreter.
 
diff --git a/docs/exceptions.rst b/docs/exceptions.rst
index 087066b8..1fbd3267 100644
--- a/docs/exceptions.rst
+++ b/docs/exceptions.rst
@@ -8,6 +8,12 @@ Exceptions
     This is raised when a context is used after being finalized.
 
 
+.. class:: InvalidSignature
+
+    This is raised when the verify method of a hash context does not
+    compare equal.
+
+
 .. class:: NotYetFinalized
 
     This is raised when the AEAD tag property is accessed on a context
diff --git a/docs/hazmat/backends/index.rst b/docs/hazmat/backends/index.rst
index a89cf0d5..06951281 100644
--- a/docs/hazmat/backends/index.rst
+++ b/docs/hazmat/backends/index.rst
@@ -1,17 +1,10 @@
 .. hazmat::
 
-Bindings
+Backends
 ========
 
-.. toctree::
-    :maxdepth: 1
-
-    openssl
-    interfaces
-
-
-Getting a Backend Provider
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Getting a Backend
+-----------------
 
 .. currentmodule:: cryptography.hazmat.backends
 
@@ -19,8 +12,7 @@ Getting a Backend Provider
 the widest number of supported cryptographic algorithms as well as supporting
 platform specific implementations.
 
-You can get the default backend by calling
-:func:`~default_backend`.
+You can get the default backend by calling :func:`~default_backend`.
 
 The default backend will change over time as we implement new backends and
 the libraries we use in those backends changes.
@@ -32,3 +24,11 @@ the libraries we use in those backends changes.
         :class:`~interfaces.CipherBackend`, :class:`~interfaces.HashBackend`, and
         :class:`~interfaces.HMACBackend`.
 
+Individual Backends
+-------------------
+
+.. toctree::
+    :maxdepth: 1
+
+    openssl
+    interfaces
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index b524943d..5b6cd64d 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -126,6 +126,17 @@ A specific ``backend`` may provide one or more of these interfaces.
     A backend with methods for using cryptographic hash functions as message
     authentication codes.
 
+    .. method:: hmac_supported(algorithm)
+
+        Check if the specified ``algorithm`` is supported by this backend.
+
+        :param algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+            provider.
+
+        :returns: ``True`` if the specified ``algorithm`` is supported for HMAC
+            by this backend, otherwise ``False``.
+
     .. method:: create_hmac_ctx(algorithm)
 
         Create a
diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst
index 12fbff04..5e51c75e 100644
--- a/docs/hazmat/backends/openssl.rst
+++ b/docs/hazmat/backends/openssl.rst
@@ -1,7 +1,7 @@
 .. hazmat::
 
-OpenSSL
-=======
+OpenSSL Backend
+===============
 
 These are `CFFI`_ bindings to the `OpenSSL`_ C library.
 
diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst
index 90ca198a..38347378 100644
--- a/docs/hazmat/primitives/cryptographic-hashes.rst
+++ b/docs/hazmat/primitives/cryptographic-hashes.rst
@@ -28,6 +28,9 @@ Message Digests
         >>> digest.finalize()
         'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90'
 
+    If the backend doesn't support the requested ``algorithm`` an
+    :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised.
+
     Keep in mind that attacks against cryptographic hashes only get stronger
     with time, and that often algorithms that were once thought to be strong,
     become broken. Because of this it's important to include a plan for
diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst
index 0c0d0220..b8f94fd2 100644
--- a/docs/hazmat/primitives/hmac.rst
+++ b/docs/hazmat/primitives/hmac.rst
@@ -34,6 +34,8 @@ message.
         >>> h.finalize()
         '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J'
 
+    If the backend doesn't support the requested ``algorithm`` an
+    :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised.
 
     :param key: Secret key as ``bytes``.
     :param algorithm: A
@@ -69,3 +71,11 @@ message.
 
         :return bytes: The message digest as bytes.
         :raises cryptography.exceptions.AlreadyFinalized:
+
+    .. method:: verify(signature)
+
+        Finalize the current context and securely compare digest to ``signature``.
+
+        :param bytes signature: The bytes of the HMAC signature recieved.
+        :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
+        :raises cryptography.exceptions.InvalidSignature: If signature does not match digest
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
index 11cff51a..361b723e 100644
--- a/docs/hazmat/primitives/interfaces.rst
+++ b/docs/hazmat/primitives/interfaces.rst
@@ -36,6 +36,17 @@ Symmetric Ciphers
         The number of bits in the key being used.
 
 
+.. class:: BlockCipherAlgorithm
+
+    A block cipher algorithm.
+
+    .. attribute:: block_size
+
+        :type: int
+
+        The number of bits in a block.
+
+
 Cipher Modes
 ------------
 
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 7b012975..e05248ff 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -61,7 +61,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_.
             provider.
 
         If the backend doesn't support the requested combination of ``cipher``
-        and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm`
+        and ``mode`` an :class:`~cryptography.exceptions.UnsupportedAlgorithm`
         will be raised.
 
     .. method:: decryptor()
@@ -352,6 +352,16 @@ Modes
                                         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
+        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
+        (32-bits). Applications **must** verify the tag is the expected length
+        to guarantee the expected security margin.
+
     :param bytes tag: The tag bytes to verify during decryption. When encrypting
                       this must be None.
 
@@ -390,3 +400,4 @@ Insecure Modes
 
 .. _`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
diff --git a/docs/index.rst b/docs/index.rst
index ab5d1593..72711174 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -32,9 +32,24 @@ existing libraries:
 * Poor introspectability, and thus poor testability.
 * Extremely error prone APIs, and bad defaults.
 
+Layout
+------
 
-Contents
---------
+``cryptography`` is broadly divided into two levels. One with safe
+cryptographic recipes, "cryptography for humans" if you will. These are safe
+and easy to use and don't require developers to make many decisions.
+
+The other level is low-level cryptographic primitives. These are often
+dangerous and can be used incorrectly. They require making decisions and having
+an in-depth knowledge of the cryptographic concepts at work. Because of the
+potential danger in working at this level, this is referred to as the
+"hazardous materials" or "hazmat" layer.
+
+We recommend using the recipes layer whenever possible, and falling back to the
+hazmat layer only when necessary.
+
+The recipes layer
+~~~~~~~~~~~~~~~~~
 
 .. toctree::
     :maxdepth: 2
@@ -43,15 +58,23 @@ Contents
     architecture
     exceptions
     glossary
-    contributing
-    security
-    community
 
-Hazardous Materials
--------------------
+The hazardous materials layer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. toctree::
     :maxdepth: 2
 
     hazmat/primitives/index
     hazmat/backends/index
+
+The ``cryptography`` open source project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+    :maxdepth: 2
+
+    contributing
+    security
+    api-stability
+    community