Merge pull request #38 from alex/why-cryptography

Better describe why this library exists. Refs #5

2 files changed, 18 insertions, 10 deletions

diff --git a/README.rst b/README.rst
index 77fcc6ca..9188106e 100644
--- a/README.rst
+++ b/README.rst
@@ -16,12 +16,3 @@ yet. It targets Python 2.6-2.7, Python 3.2+, as well as PyPy.
 You can find more documentation at `Read The Docs`_.
 
 .. _`Read The Docs`: https://cryptography.readthedocs.org/
-
-
-Why a new crypto library for Python?
-------------------------------------
-
-None of the existing ones work on PyPy, and many of them are unmaintained or
-are based around very poor implementations of algorithms (i.e ones with known
-side-channel attacks).
-
diff --git a/docs/index.rst b/docs/index.rst
index 1d8ffda6..29f0b545 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,7 +8,24 @@ Welcome to ``cryptography``
 ``cryptography`` is a Python library which exposes cryptographic primitives and
 recipes.
 
-Contents:
+Why a new crypto library for Python?
+------------------------------------
+
+We wanted to address a few issues with existing cryptography libraries in
+Python:
+
+* Lack of PyPy support.
+* Lack of maintenance.
+* Use of poor implementations of algorithms (i.e. ones with known side-channel
+  attacks).
+* Lack of high level, "Cryptography for humans", APIs.
+* Absence of algorithms such as AES-GCM.
+* Poor introspectability, and thus poor testability.
+* Extremely error prone APIs, and bad defaults.
+
+
+Contents
+--------
 
 .. toctree::
     :maxdepth: 2