diff options
Diffstat (limited to 'docs/hazmat')
-rw-r--r-- | docs/hazmat/backends/openssl.rst | 50 | ||||
-rw-r--r-- | docs/hazmat/primitives/padding.rst | 10 | ||||
-rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 24 |
3 files changed, 66 insertions, 18 deletions
diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 4db3972d..ea72af96 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -16,10 +16,58 @@ The `OpenSSL`_ C library. * :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` * :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend` - It has one additional public attribute. + It also exposes the following: .. attribute:: name The string name of this backend: ``"openssl"`` + .. method:: activate_osrandom_engine() + + Activates the OS random engine. This will effectively disable OpenSSL's + default CSPRNG. + + .. method:: activate_builtin_random() + + This will activate the default OpenSSL CSPRNG. + +OS Random Engine +---------------- + +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 +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. When +active this engine will be used to generate all the random data OpenSSL +requests. + +When importing only the binding it is added to the engine list but +**not activated**. + + +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 same pool as ``/dev/random``. + + .. _`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) diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst index 4d79ac8f..da5a95dd 100644 --- a/docs/hazmat/primitives/padding.rst +++ b/docs/hazmat/primitives/padding.rst @@ -54,11 +54,11 @@ multiple of the block size. .. class:: PaddingContext - When calling ``padder()`` or ``unpadder()`` you will receive an a return - object conforming to the ``PaddingContext`` interface. You can then call - ``update(data)`` with data until you have fed everything into the context. - Once that is done call ``finalize()`` to finish the operation and obtain - the remainder of the data. + When calling ``padder()`` or ``unpadder()`` the result will conform to the + ``PaddingContext`` interface. You can then call ``update(data)`` with data + until you have fed everything into the context. Once that is done call + ``finalize()`` to finish the operation and obtain the remainder of the + data. .. method:: update(data) diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 7d954046..85d8e8e3 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -388,10 +388,10 @@ Interfaces .. class:: CipherContext When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object - you will receive a return object conforming to the ``CipherContext`` - interface. You can then call ``update(data)`` with data until you have fed - everything into the context. Once that is done call ``finalize()`` to - finish the operation and obtain the remainder of the data. + the result will conform to the ``CipherContext`` interface. You can then + call ``update(data)`` with data until you have fed everything into the + context. Once that is done call ``finalize()`` to finish the operation and + obtain the remainder of the data. Block ciphers require that plaintext or ciphertext always be a multiple of their block size, because of that **padding** is sometimes required to make @@ -429,14 +429,14 @@ Interfaces When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object with an AEAD mode (e.g. - :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) you will receive - a return object conforming to the ``AEADCipherContext`` and - ``CipherContext`` interfaces. If it is an encryption context it will - additionally be an ``AEADEncryptionContext`` interface. - ``AEADCipherContext`` contains an additional method - ``authenticate_additional_data`` for adding additional authenticated but - unencrypted data (see note below). You should call this before calls to - ``update``. When you are done call ``finalize()`` to finish the operation. + :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) the result will + conform to the ``AEADCipherContext`` and ``CipherContext`` interfaces. If + it is an encryption context it will additionally be an + ``AEADEncryptionContext`` interface. ``AEADCipherContext`` contains an + additional method ``authenticate_additional_data`` for adding additional + authenticated but unencrypted data (see note below). You should call this + before calls to ``update``. When you are done call ``finalize()`` to finish + the operation. .. note:: |