From 3f17c7c68157ec04b98cb5fd61216a6644aa3a7c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 20 Jan 2014 16:32:26 -0600 Subject: 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 --- docs/hazmat/backends/openssl.rst | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) (limited to 'docs/hazmat/backends') 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 ------------------------------- -- cgit v1.2.3 From 136ff17aceac8b61cd1c3f12774c3d1f9cf6742a Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 21:23:11 -0600 Subject: update random engine docs --- docs/hazmat/backends/openssl.rst | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) (limited to 'docs/hazmat/backends') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 5ad00d03..17d01ca8 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -28,15 +28,25 @@ The `OpenSSL`_ C library. 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. +OpenSSL uses a userspace 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. It is +added to the engine list but **not activated** if you only import the binding. +If you wish to deactivate it call ``unregister_osrandom_engine()`` on the +backend object. .. _`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) -- cgit v1.2.3 From 9967bc5c378ea2e72cc6c034e22bca6588ca2f29 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 21:39:13 -0600 Subject: add a little info about the various system randoms. maybe useful? --- docs/hazmat/backends/openssl.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/hazmat/backends') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 17d01ca8..16519d18 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -46,6 +46,18 @@ added to the engine list but **not activated** if you only import the binding. If you wish to deactivate it call ``unregister_osrandom_engine()`` on the backend object. +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 ``/dev/random`` pool. + + .. _`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 -- cgit v1.2.3 From 55809a16fd82f414774252f9788593776ad26687 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 21:41:16 -0600 Subject: rst syntax --- docs/hazmat/backends/openssl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat/backends') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 16519d18..b7133deb 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -47,7 +47,7 @@ If you wish to deactivate it call ``unregister_osrandom_engine()`` on the backend object. OS Random Sources ----------------------------- +----------------- On OS X and FreeBSD ``/dev/urandom`` is an alias for ``/dev/random`` and utilizes the `Yarrow`_ algorithm. -- cgit v1.2.3 From ae2138aaa2049cd066a3679ff4d82f57b6843d61 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 29 Jan 2014 22:19:47 -0600 Subject: add a hyphen to please the spellcheck gods --- docs/hazmat/backends/openssl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat/backends') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index b7133deb..8eb02ea4 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -28,7 +28,7 @@ The `OpenSSL`_ C library. OS Random Engine ---------------- -OpenSSL uses a userspace CSPRNG that is seeded from system random ( +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 -- cgit v1.2.3 From 16e5e4d2659a0e6cbea44f561914142c80554a73 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 30 Jan 2014 09:43:30 -0600 Subject: address review comments on osrandom engine, reorganize some code --- docs/hazmat/backends/openssl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat/backends') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 8eb02ea4..79c58857 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -55,7 +55,7 @@ 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 ``/dev/random`` pool. +from the same pool as ``/dev/random``. .. _`OpenSSL`: https://www.openssl.org/ -- cgit v1.2.3 From 8042b2988d71d3675e06d25416e285215ae98636 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 31 Jan 2014 10:44:36 -0600 Subject: more explanation of what an active osrandom engine means --- docs/hazmat/backends/openssl.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) (limited to 'docs/hazmat/backends') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 79c58857..81361f5a 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -41,10 +41,16 @@ its entropy from ``/dev/urandom`` on UNIX-like operating systems and uses 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. It is -added to the engine list but **not activated** if you only import the binding. -If you wish to deactivate it call ``unregister_osrandom_engine()`` on the -backend object. +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. + +If you wish to deactivate the engine you may call +``unregister_osrandom_engine()`` on the backend object. + +When importing only the binding it is added to the engine list but +**not activated**. + OS Random Sources ----------------- -- cgit v1.2.3 From d52b89b4e881639bc68d9c30983e08a1b8085be8 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 31 Jan 2014 10:57:17 -0600 Subject: change register/unregister to activate/deactivate --- docs/hazmat/backends/openssl.rst | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) (limited to 'docs/hazmat/backends') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 81361f5a..1d40b93c 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -13,14 +13,14 @@ The `OpenSSL`_ C library. The string name of this backend: ``"openssl"`` - .. method:: register_osrandom_engine() + .. method:: activate_osrandom_engine() - Registers the OS random engine as default. This will effectively - disable OpenSSL's default CSPRNG. + Activates the OS random engine. This will effectively disable OpenSSL's + default CSPRNG. - .. method:: unregister_osrandom_engine() + .. method:: deactivate_osrandom_engine() - Unregisters the OS random engine if it is default. This will restore + Deactivates 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. @@ -45,9 +45,6 @@ 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. -If you wish to deactivate the engine you may call -``unregister_osrandom_engine()`` on the backend object. - When importing only the binding it is added to the engine list but **not activated**. -- cgit v1.2.3 From d258222091c9ac2d5a701debca356e3d9a3f8559 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 5 Feb 2014 16:21:19 -0600 Subject: remove deactivate and replace with activate_builtin_random --- docs/hazmat/backends/openssl.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) (limited to 'docs/hazmat/backends') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index f7d6b710..ea72af96 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -27,12 +27,9 @@ The `OpenSSL`_ C library. Activates the OS random engine. This will effectively disable OpenSSL's default CSPRNG. - .. method:: deactivate_osrandom_engine() + .. method:: activate_builtin_random() - Deactivates 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. + This will activate the default OpenSSL CSPRNG. OS Random Engine ---------------- -- cgit v1.2.3