first pass at adding docs for the engine.
lvh has graciously agreed to draft some language to explain the
rationale behind choosing the system random over userspace rand
diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst
index a1f2d28..469823f 100644
--- a/docs/hazmat/backends/openssl.rst
+++ b/docs/hazmat/backends/openssl.rst
@@ -7,12 +7,39 @@
.. data:: cryptography.hazmat.backends.openssl.backend
- This is the exposed API for the OpenSSL backend. It has one public attribute.
+ This is the exposed API for the OpenSSL backend.
.. attribute:: name
The string name of this backend: ``"openssl"``
+ .. method:: register_osrandom_engine()
+
+ Registers the OS random engine as default. This will effectively
+ disable OpenSSL's default CSPRNG.
+
+ .. method:: unregister_osrandom_engine()
+
+ Unregisters the OS random engine if it is default. This will restore
+ the default OpenSSL CSPRNG. If the OS random engine is not the default
+ engine (e.g. if another engine is set as default) nothing will be
+ changed.
+
+OS Random Engine
+----------------
+
+OpenSSL has a CSPRNG that it seeds when starting up. Unfortunately, its state
+is replicated when the process is forked and child processes can deliver
+similar or identical random values. OpenSSL has landed a patch to mitigate this
+issue, but this project can't rely on users having recent versions.
+
+To work around this cryptography uses a custom OpenSSL engine that replaces the
+standard random source with one that fetches entropy from ``/dev/urandom`` (or
+CryptGenRandom on Windows). This engine is **active** by default when importing
+the OpenSSL backend. It is added to the engine list but not activated if you
+only import the binding.
+
+
Using your own OpenSSL on Linux
-------------------------------
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index 75628ba..e05efc6 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -27,3 +27,4 @@
Docstrings
Fernet
Schneier
+Unregisters