| Alex Gaynor | af82d5e | 2013-10-29 17:07:24 -0700 | [diff] [blame] | 1 | .. hazmat:: |
| Alex Gaynor | 0f7f781 | 2013-09-30 10:52:36 -0700 | [diff] [blame] | 2 | |
| Alex Gaynor | 8f42fe4 | 2013-12-24 13:15:52 -0800 | [diff] [blame] | 3 | OpenSSL Backend |
| 4 | =============== |
| Donald Stufft | e51fb93 | 2013-10-27 17:26:17 -0400 | [diff] [blame] | 5 | |
| Alex Stapleton | c368ac2 | 2013-12-31 13:43:38 +0000 | [diff] [blame] | 6 | The `OpenSSL`_ C library. |
| Alex Gaynor | 6d02e2d | 2013-09-30 10:37:22 -0700 | [diff] [blame] | 7 | |
| Alex Gaynor | f8796b1 | 2013-12-13 20:28:55 -0800 | [diff] [blame] | 8 | .. data:: cryptography.hazmat.backends.openssl.backend |
| Alex Gaynor | 6d02e2d | 2013-09-30 10:37:22 -0700 | [diff] [blame] | 9 | |
| Paul Kehrer | 3f17c7c | 2014-01-20 16:32:26 -0600 | [diff] [blame] | 10 | This is the exposed API for the OpenSSL backend. |
| Paul Kehrer | 2502ce5 | 2014-01-18 09:32:47 -0600 | [diff] [blame] | 11 | |
| Paul Kehrer | cfa2d62 | 2014-01-19 14:01:25 -0600 | [diff] [blame] | 12 | .. attribute:: name |
| Paul Kehrer | 2502ce5 | 2014-01-18 09:32:47 -0600 | [diff] [blame] | 13 | |
| Paul Kehrer | cfa2d62 | 2014-01-19 14:01:25 -0600 | [diff] [blame] | 14 | The string name of this backend: ``"openssl"`` |
| Alex Gaynor | 6d02e2d | 2013-09-30 10:37:22 -0700 | [diff] [blame] | 15 | |
| Paul Kehrer | 3f17c7c | 2014-01-20 16:32:26 -0600 | [diff] [blame] | 16 | .. method:: register_osrandom_engine() |
| 17 | |
| 18 | Registers the OS random engine as default. This will effectively |
| 19 | disable OpenSSL's default CSPRNG. |
| 20 | |
| 21 | .. method:: unregister_osrandom_engine() |
| 22 | |
| 23 | Unregisters the OS random engine if it is default. This will restore |
| 24 | the default OpenSSL CSPRNG. If the OS random engine is not the default |
| 25 | engine (e.g. if another engine is set as default) nothing will be |
| 26 | changed. |
| 27 | |
| 28 | OS Random Engine |
| 29 | ---------------- |
| 30 | |
| 31 | OpenSSL has a CSPRNG that it seeds when starting up. Unfortunately, its state |
| 32 | is replicated when the process is forked and child processes can deliver |
| 33 | similar or identical random values. OpenSSL has landed a patch to mitigate this |
| 34 | issue, but this project can't rely on users having recent versions. |
| 35 | |
| 36 | To work around this cryptography uses a custom OpenSSL engine that replaces the |
| 37 | standard random source with one that fetches entropy from ``/dev/urandom`` (or |
| 38 | CryptGenRandom on Windows). This engine is **active** by default when importing |
| 39 | the OpenSSL backend. It is added to the engine list but not activated if you |
| 40 | only import the binding. |
| 41 | |
| Alex Gaynor | 6d02e2d | 2013-09-30 10:37:22 -0700 | [diff] [blame] | 42 | .. _`OpenSSL`: https://www.openssl.org/ |