diff options
Diffstat (limited to 'docs/hazmat/backends/openssl.rst')
| -rw-r--r-- | docs/hazmat/backends/openssl.rst | 56 |
1 files changed, 49 insertions, 7 deletions
diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 03ac5570..56121cb5 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -3,9 +3,8 @@ OpenSSL backend =============== -The `OpenSSL`_ C library. Cryptography supports version ``0.9.8e`` (present in -Red Hat Enterprise Linux 5) and greater. Earlier versions may work but are -**not tested or supported**. +The `OpenSSL`_ C library. Cryptography supports OpenSSL version 1.0.2 and +greater. .. data:: cryptography.hazmat.backends.openssl.backend @@ -16,6 +15,7 @@ Red Hat Enterprise Linux 5) and greater. Earlier versions may work but are * :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` * :class:`~cryptography.hazmat.backends.interfaces.CMACBackend` * :class:`~cryptography.hazmat.backends.interfaces.DERSerializationBackend` + * :class:`~cryptography.hazmat.backends.interfaces.DHBackend` * :class:`~cryptography.hazmat.backends.interfaces.DSABackend` * :class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend` * :class:`~cryptography.hazmat.backends.interfaces.HashBackend` @@ -25,17 +25,42 @@ Red Hat Enterprise Linux 5) and greater. Earlier versions may work but are * :class:`~cryptography.hazmat.backends.interfaces.PEMSerializationBackend` * :class:`~cryptography.hazmat.backends.interfaces.X509Backend` + It also implements the following interface for OpenSSL versions ``1.1.0`` + and above. + + * :class:`~cryptography.hazmat.backends.interfaces.ScryptBackend` + It also exposes the following: .. attribute:: name The string name of this backend: ``"openssl"`` + .. method:: openssl_version_text() + + :return text: The friendly string name of the loaded OpenSSL library. + This is not necessarily the same version as it was compiled against. + + .. method:: openssl_version_number() + + .. versionadded:: 1.8 + + :return int: The integer version of the loaded OpenSSL library. This is + defined in ``opensslv.h`` as ``OPENSSL_VERSION_NUMBER`` and is + typically shown in hexadecimal (e.g. ``0x1010003f``). This is + not necessarily the same version as it was compiled against. + .. method:: activate_osrandom_engine() Activates the OS random engine. This will effectively disable OpenSSL's default CSPRNG. + .. method:: osrandom_engine_implementation() + + .. versionadded:: 1.7 + + Returns the implementation of OS random engine. + .. method:: activate_builtin_random() This will activate the default OpenSSL CSPRNG. @@ -43,7 +68,7 @@ Red Hat Enterprise Linux 5) and greater. Earlier versions may work but are OS random engine ---------------- -OpenSSL uses a user-space CSPRNG that is seeded from system random ( +By default 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 @@ -67,8 +92,9 @@ When importing only the binding it is added to the engine list but OS random sources ----------------- -On OS X and FreeBSD ``/dev/urandom`` is an alias for ``/dev/random`` and -utilizes the `Yarrow`_ algorithm. +On macOS and FreeBSD ``/dev/urandom`` is an alias for ``/dev/random``. The +implementation on macOS uses the `Yarrow`_ algorithm. FreeBSD uses the +`Fortuna`_ algorithm. On Windows the implementation of ``CryptGenRandom`` depends on which version of the operation system you are using. See the `Microsoft documentation`_ for more @@ -77,8 +103,24 @@ details. Linux uses its own PRNG design. ``/dev/urandom`` is a non-blocking source seeded from the same pool as ``/dev/random``. ++------------------------------------------+------------------------------+ +| Windows | ``CryptGenRandom()`` | ++------------------------------------------+------------------------------+ +| Linux >= 3.17 with working | ``getrandom()`` | +| ``SYS_getrandom`` syscall | | ++------------------------------------------+------------------------------+ +| OpenBSD >= 5.6 | ``getentropy()`` | ++------------------------------------------+------------------------------+ +| BSD family (including macOS 10.12+) with | ``getentropy()`` | +| ``SYS_getentropy`` in ``sys/syscall.h`` | | ++------------------------------------------+------------------------------+ +| fallback | ``/dev/urandom`` with | +| | cached file descriptor | ++------------------------------------------+------------------------------+ + .. _`OpenSSL`: https://www.openssl.org/ .. _`initializing the RNG`: https://en.wikipedia.org/wiki/OpenSSL#Predictable_private_keys_.28Debian-specific.29 +.. _`Fortuna`: https://en.wikipedia.org/wiki/Fortuna_(PRNG) .. _`Yarrow`: https://en.wikipedia.org/wiki/Yarrow_algorithm -.. _`Microsoft documentation`: https://msdn.microsoft.com/en-us/library/windows/desktop/aa379942(v=vs.85).aspx +.. _`Microsoft documentation`: https://docs.microsoft.com/en-us/windows/desktop/api/wincrypt/nf-wincrypt-cryptgenrandom |