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 /docs | |
| 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
Diffstat (limited to 'docs')
| -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 |