diff options
| author | Paul Kehrer <paul.l.kehrer@gmail.com> | 2014-01-20 16:32:26 -0600 |
|---|---|---|
| committer | Paul Kehrer <paul.l.kehrer@gmail.com> | 2014-01-20 16:32:26 -0600 |
| commit | 3f17c7c68157ec04b98cb5fd61216a6644aa3a7c (patch) | |
| tree | cc5ff985b8fa540af456e887e81f7e3b841c2948 | |
| parent | 81a68fc96d0845f5ee812665405276a935d05a79 (diff) | |
| download | cryptography-3f17c7c68157ec04b98cb5fd61216a6644aa3a7c.tar.gz cryptography-3f17c7c68157ec04b98cb5fd61216a6644aa3a7c.tar.bz2 cryptography-3f17c7c68157ec04b98cb5fd61216a6644aa3a7c.zip | |
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
| -rw-r--r-- | docs/hazmat/backends/openssl.rst | 29 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 1 |
2 files changed, 29 insertions, 1 deletions
diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index a1f2d28a..469823f1 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -7,12 +7,39 @@ The `OpenSSL`_ C library. .. 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 75628ba5..e05efc6c 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -27,3 +27,4 @@ Changelog Docstrings Fernet Schneier +Unregisters |