3 files changed, 66 insertions, 18 deletions
diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst
index 4db3972d..ea72af96 100644
--- a/docs/hazmat/backends/openssl.rst
+++ b/docs/hazmat/backends/openssl.rst
@@ -16,10 +16,58 @@ The `OpenSSL`_ C library.
     * :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
     * :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend`
 
-    It has one additional public attribute.
+    It also exposes the following:
 
     .. attribute:: name
 
         The string name of this backend: ``"openssl"``
 
+    .. method:: activate_osrandom_engine()
+
+        Activates the OS random engine. This will effectively disable OpenSSL's
+        default CSPRNG.
+
+    .. method:: activate_builtin_random()
+
+        This will activate the default OpenSSL CSPRNG.
+
+OS Random Engine
+----------------
+
+OpenSSL uses a user-space CSPRNG that is seeded from system random (
+``/dev/urandom`` or ``CryptGenRandom``). This CSPRNG is not reseeded
+automatically when a process calls ``fork()``. This can result in situations
+where two different processes can return similar or identical keys and
+compromise the security of the system.
+
+The approach this project has chosen to mitigate this vulnerability is to
+include an engine that replaces the OpenSSL default CSPRNG with one that sources
+its entropy from ``/dev/urandom`` on UNIX-like operating systems and uses
+``CryptGenRandom`` on Windows. This method of pulling from the system pool
+allows us to avoid potential issues with `initializing the RNG`_ as well as
+protecting us from the ``fork()`` weakness.
+
+This engine is **active** by default when importing the OpenSSL backend. When
+active this engine will be used to generate all the random data OpenSSL
+requests.
+
+When importing only the binding it is added to the engine list but
+**not activated**.
+
+
+OS Random Sources
+-----------------
+
+On OS X and FreeBSD ``/dev/urandom`` is an alias for ``/dev/random`` and
+utilizes the `Yarrow`_ algorithm.
+
+On Windows ``CryptGenRandom`` is backed by `Fortuna`_.
+
+Linux uses its own PRNG design. ``/dev/urandom`` is a non-blocking source seeded
+from the same pool as ``/dev/random``.
+
+
 .. _`OpenSSL`: https://www.openssl.org/
+.. _`initializing the RNG`: http://en.wikipedia.org/wiki/OpenSSL#Vulnerability_in_the_Debian_implementation
+.. _`Yarrow`: http://en.wikipedia.org/wiki/Yarrow_algorithm
+.. _`Fortuna`: http://en.wikipedia.org/wiki/Fortuna_(PRNG)
diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst
index 4d79ac8f..da5a95dd 100644
--- a/docs/hazmat/primitives/padding.rst
+++ b/docs/hazmat/primitives/padding.rst
@@ -54,11 +54,11 @@ multiple of the block size.
 
 .. class:: PaddingContext
 
-    When calling ``padder()`` or ``unpadder()`` you will receive an a return
-    object conforming to the ``PaddingContext`` interface. You can then call
-    ``update(data)`` with data until you have fed everything into the context.
-    Once that is done call ``finalize()`` to finish the operation and obtain
-    the remainder of the data.
+    When calling ``padder()`` or ``unpadder()`` the result will conform to the
+    ``PaddingContext`` interface. You can then call ``update(data)`` with data
+    until you have fed everything into the context. Once that is done call
+    ``finalize()`` to finish the operation and obtain the remainder of the
+    data.
 
     .. method:: update(data)
 
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 7d954046..85d8e8e3 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -388,10 +388,10 @@ Interfaces
 .. class:: CipherContext
 
     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
-    finish the operation and obtain the remainder of the data.
+    the result will conform 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 finish the operation and
+    obtain the remainder of the data.
 
     Block ciphers require that plaintext or ciphertext always be a multiple of
     their block size, because of that **padding** is sometimes required to make
@@ -429,14 +429,14 @@ Interfaces
 
     When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object
     with an AEAD mode (e.g.
-    :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) you will receive
-    a return object conforming to the ``AEADCipherContext`` and
-    ``CipherContext`` interfaces. If it is an encryption context it will
-    additionally be an ``AEADEncryptionContext`` interface.
-    ``AEADCipherContext`` contains an additional method
-    ``authenticate_additional_data`` for adding additional authenticated but
-    unencrypted data (see note below). You should call this before calls to
-    ``update``. When you are done call ``finalize()`` to finish the operation.
+    :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) the result will
+    conform to the ``AEADCipherContext`` and ``CipherContext`` interfaces. If
+    it is an encryption context it will additionally be an
+    ``AEADEncryptionContext`` interface. ``AEADCipherContext`` contains an
+    additional method ``authenticate_additional_data`` for adding additional
+    authenticated but unencrypted data (see note below). You should call this
+    before calls to ``update``. When you are done call ``finalize()`` to finish
+    the operation.
 
     .. note::