6 files changed, 159 insertions, 8 deletions
diff --git a/docs/community.rst b/docs/community.rst
index 86ba5055..552318da 100644
--- a/docs/community.rst
+++ b/docs/community.rst
@@ -12,4 +12,4 @@ You can find ``cryptography`` all over the web:
 .. _`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.readthedocs.org/
+.. _`Documentation`: https://cryptography.io/
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 2d8fceeb..6a76c705 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -20,8 +20,8 @@ devastating, ``cryptography`` has a strict code review policy:
 * Patches must *never* be pushed directly to ``master``, all changes (even the
   most trivial typo fixes!) must be submitted as a pull request.
 * A committer may *never* merge their own pull request, a second party must
-  merge their changes. If multiple people work on a pull request, the merger
-  may not be any of them.
+  merge their changes. If multiple people work on a pull request, it must be
+  merged by someone who did not work on it.
 * A patch which breaks tests, or introduces regressions by changing or removing
   existing tests should not be merged. Tests must always be passing on
   ``master``.
@@ -32,11 +32,8 @@ devastating, ``cryptography`` has a strict code review policy:
 The purpose of these policies is to minimize the chances we merge a change
 which jeopardizes our users' security.
 
-We do not yet have a formal security contact. To report security issues in
-``cryptography`` you should email ``alex.gaynor@gmail.com``, messages may be
-encrypted with PGP to key fingerprint
-``E27D 4AA0 1651 72CB C5D2  AF2B 125F 5C67 DFE9 4084`` (this public key is
-available from most commonly-used keyservers).
+If you believe you've identified a security issue in ``cryptography``, please
+follow the directions on the :doc:`security page </security>`.
 
 Code
 ----
@@ -50,6 +47,58 @@ Additionally, every Python code file must contain
 
     from __future__ import absolute_import, division, print_function
 
+C bindings
+----------
+
+When binding C code with ``cffi`` we have our own style guide, it's pretty
+simple.
+
+Don't name parameters:
+
+.. code-block:: c
+
+    // Good
+    long f(long);
+    // Bad
+    long f(long x);
+
+...unless they're inside a struct:
+
+.. code-block:: c
+
+    struct my_struct {
+        char *name;
+        int number;
+        ...;
+    };
+
+Don't include stray ``void`` parameters:
+
+.. code-block:: c
+
+    // Good
+    long f();
+    // Bad
+    long f(void);
+
+Wrap lines at 80 characters like so:
+
+.. code-block:: c
+
+    // Pretend this went to 80 characters
+    long f(long, long,
+           int *)
+
+Include a space after commas between parameters:
+
+.. code-block:: c
+
+    // Good
+    long f(int, char *)
+    // Bad
+    long f(int,char *)
+
+
 Documentation
 -------------
 
diff --git a/docs/index.rst b/docs/index.rst
index 5cc455f6..a868a5d6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -34,4 +34,5 @@ Contents
     primitives/index
     bindings/index
     contributing
+    security
     community
diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst
new file mode 100644
index 00000000..d4dde042
--- /dev/null
+++ b/docs/primitives/cryptographic-hashes.rst
@@ -0,0 +1,88 @@
+Message Digests
+===============
+
+.. class:: cryptography.primitives.hashes.BaseHash
+
+   Abstract base class that implements a common interface for all hash
+   algorithms that follow here.
+
+    .. method:: update(data)
+
+        :param bytes data: The bytes you wish to hash.
+
+    .. method:: copy()
+
+        :return: a new instance of this object with a copied internal state.
+
+    .. method:: digest()
+
+        :return bytes: The message digest as bytes.
+
+    .. method:: hexdigest()
+
+        :return str: The message digest as hex.
+
+SHA-1
+~~~~~
+
+.. attention::
+
+    NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications
+    are strongly suggested to use SHA-2 over SHA-1.
+
+.. class:: cryptography.primitives.hashes.SHA1()
+
+    SHA-1 is a cryptographic hash function standardized by NIST. It has a
+    160-bit message digest.
+
+SHA-2 Family
+~~~~~~~~~~~~
+
+.. class:: cryptography.primitives.hashes.SHA224()
+
+    SHA-224 is a cryptographic hash function from the SHA-2 family and
+    standardized by NIST. It has a 224-bit message digest.
+
+.. class:: cryptography.primitives.hashes.SHA256()
+
+    SHA-256 is a cryptographic hash function from the SHA-2 family and
+    standardized by NIST. It has a 256-bit message digest.
+
+.. class:: cryptography.primitives.hashes.SHA384()
+
+    SHA-384 is a cryptographic hash function from the SHA-2 family and
+    standardized by NIST. It has a 384-bit message digest.
+
+.. class:: cryptography.primitives.hashes.SHA512()
+
+    SHA-512 is a cryptographic hash function from the SHA-2 family and
+    standardized by NIST. It has a 512-bit message digest.
+
+RIPEMD160
+~~~~~~~~~
+
+.. class:: cryptography.primitives.hashes.RIPEMD160()
+
+    RIPEMD160 is a cryptographic hash function that is part of ISO/IEC
+    10118-3:2004. It has a 160-bit message digest.
+
+Whirlpool
+~~~~~~~~~
+
+.. class:: cryptography.primitives.hashes.Whirlpool()
+
+    Whirlpool is a cryptographic hash function that is part of ISO/IEC
+    10118-3:2004. It has a 512-bit message digest.
+
+MD5
+~~~
+
+.. warning::
+
+    MD5 is a deprecated hash algorithm that has practical known collision
+    attacks. You are strongly discouraged from using it.
+
+.. class:: cryptography.primitives.hashes.MD5()
+
+    MD5 is a deprecated cryptographic hash function. It has a 160-bit message
+    digest and has practical known collision attacks.
diff --git a/docs/primitives/index.rst b/docs/primitives/index.rst
index 1066e30e..c18c62ca 100644
--- a/docs/primitives/index.rst
+++ b/docs/primitives/index.rst
@@ -4,4 +4,5 @@ Primitives
 .. toctree::
     :maxdepth: 1
 
+    cryptographic-hashes
     symmetric-encryption
diff --git a/docs/security.rst b/docs/security.rst
new file mode 100644
index 00000000..36c8e0f7
--- /dev/null
+++ b/docs/security.rst
@@ -0,0 +1,12 @@
+Security
+========
+
+We take the security of ``cryptography`` seriously. If you believe you've
+identified a security issue in it, please report it to
+``alex.gaynor@gmail.com``. Message may be encrypted with PGP using key
+fingerprint ``E27D 4AA0 1651 72CB C5D2  AF2B 125F 5C67 DFE9 4084`` (this public
+key is available from most commonly-used keyservers).
+
+Once you’ve submitted an issue via email, you should receive an acknowledgment
+within 48 hours, and depending on the action to be taken, you may receive
+further followup emails.