Merge branch 'master' into pbkdf2-commoncrypto

* master:
  a bit more language work + changelog changes for pbkdf2hmac
  one more style fix
  a few typo fixes, capitalization, etc
  switch to private attributes in pbkdf2hmac
  expand docs to talk more about the purposes of KDFs
  update docs re: PBKDF2HMAC iterations
  add test for null char replacement
  Added installation section to index.rst
  called -> used
  quotes inside, diff examples
  Expose this method because probably someone will need it eventually
  fix spacing, remove versionadded since HashAlgorithm was in 0.1
  document HashAlgorithm
  Added canonical installation document with details about various platforms, fixes #519
  update docs for pbkdf2
  Add bindings for X509_REQ_get_extensions.
  add Konstantinos Koukopoulos to AUTHORS.rst
  review fixes
  doc updates based on review

Conflicts:
	docs/changelog.rst

1 files changed, 74 insertions, 0 deletions

diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644
index 00000000..2206107e
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,74 @@
+Installing
+==========
+
+You can install ``cryptography`` with ``pip``:
+
+.. code-block:: console
+
+    $ pip install cryptography
+
+Installation Notes
+==================
+On Windows
+----------
+If you're on Windows you'll need to make sure you have OpenSSL installed.
+There are `pre-compiled binaries`_ available. If your installation is in
+an unusual location set the ``LIB`` and ``INCLUDE`` environment variables
+to include the corresponding locations. For example:
+
+.. code-block:: console
+
+    C:\> \path\to\vcvarsall.bat x86_amd64
+    C:\> set LIB=C:\OpenSSL-1.0.1f-64bit\lib;%LIB%
+    C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE%
+    C:\> pip install cryptography
+
+Using your own OpenSSL on Linux
+-------------------------------
+
+Python links to OpenSSL for its own purposes and this can sometimes cause
+problems when you wish to use a different version of OpenSSL with cryptography.
+If you want to use cryptography with your own build of OpenSSL you will need to
+make sure that the build is configured correctly so that your version of
+OpenSSL doesn't conflict with Python's.
+
+The options you need to add allow the linker to identify every symbol correctly
+even when multiple versions of the library are linked into the same program. If
+you are using your distribution's source packages these will probably be
+patched in for you already, otherwise you'll need to use options something like
+this when configuring OpenSSL:
+
+.. code-block:: console
+
+    $ ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared
+
+You'll also need to generate your own ``openssl.ld`` file. For example::
+
+    OPENSSL_1.0.1F_CUSTOM {
+        global:
+            *;
+    };
+
+You should replace the version string on the first line as appropriate for your
+build.
+
+Using your own OpenSSL on OS X
+------------------------------
+
+To link cryptography against a custom version of OpenSSL you'll need to set
+``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. OpenSSL can be installed via
+`Homebrew`_:
+
+.. code-block:: console
+
+    $ brew install openssl
+
+Then install cryptography linking against the brewed version:
+
+.. code-block:: console
+
+    $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography
+
+
+.. _`Homebrew`: http://brew.sh
+.. _`pre-compiled binaries`: https://www.openssl.org/related/binaries.html