Skip to content

Latest commit

 

History

History
132 lines (94 loc) · 5.42 KB

openssl.rst

File metadata and controls

132 lines (94 loc) · 5.42 KB
Raw
.. hazmat::

OpenSSL backend

The OpenSSL C library. Cryptography supports OpenSSL version 1.0.2 and greater.

.. data:: cryptography.hazmat.backends.openssl.backend

    This is the exposed API for the OpenSSL backend.

    It implements the following interfaces:

    * :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`
    * :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
    * :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend`
    * :class:`~cryptography.hazmat.backends.interfaces.RSABackend`
    * :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.

OS random engine

Note

As of OpenSSL 1.1.1d its CSPRNG is fork-safe by default. cryptography does not compile or load the custom engine on these versions.

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 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 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 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 SYS_getrandom syscall getrandom()
OpenBSD >= 5.6 getentropy()
BSD family (including macOS 10.12+) with SYS_getentropy in sys/syscall.h getentropy()
fallback /dev/urandom with cached file descriptor