• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. hazmat::
2
3OpenSSL backend
4===============
5
6The `OpenSSL`_ C library. Cryptography supports OpenSSL version 1.0.1 and
7greater.
8
9.. data:: cryptography.hazmat.backends.openssl.backend
10
11    This is the exposed API for the OpenSSL backend.
12
13    It implements the following interfaces:
14
15    * :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
16    * :class:`~cryptography.hazmat.backends.interfaces.CMACBackend`
17    * :class:`~cryptography.hazmat.backends.interfaces.DERSerializationBackend`
18    * :class:`~cryptography.hazmat.backends.interfaces.DHBackend`
19    * :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
20    * :class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend`
21    * :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
22    * :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
23    * :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend`
24    * :class:`~cryptography.hazmat.backends.interfaces.RSABackend`
25    * :class:`~cryptography.hazmat.backends.interfaces.PEMSerializationBackend`
26    * :class:`~cryptography.hazmat.backends.interfaces.X509Backend`
27
28    It also implements the following interface for OpenSSL versions ``1.1.0``
29    and above.
30
31    * :class:`~cryptography.hazmat.backends.interfaces.ScryptBackend`
32
33    It also exposes the following:
34
35    .. attribute:: name
36
37        The string name of this backend: ``"openssl"``
38
39    .. method:: openssl_version_text()
40
41        :return text: The friendly string name of the loaded OpenSSL library.
42            This is not necessarily the same version as it was compiled against.
43
44    .. method:: openssl_version_number()
45
46        .. versionadded:: 1.8
47
48        :return int: The integer version of the loaded OpenSSL library. This is
49            defined in ``opensslv.h`` as ``OPENSSL_VERSION_NUMBER`` and is
50            typically shown in hexadecimal (e.g. ``0x1010003f``). This is
51            not necessarily the same version as it was compiled against.
52
53    .. method:: activate_osrandom_engine()
54
55        Activates the OS random engine. This will effectively disable OpenSSL's
56        default CSPRNG.
57
58    .. method:: osrandom_engine_implementation()
59
60        .. versionadded:: 1.7
61
62        Returns the implementation of OS random engine.
63
64    .. method:: activate_builtin_random()
65
66        This will activate the default OpenSSL CSPRNG.
67
68OS random engine
69----------------
70
71By default OpenSSL uses a user-space CSPRNG that is seeded from system random (
72``/dev/urandom`` or ``CryptGenRandom``). This CSPRNG is not reseeded
73automatically when a process calls ``fork()``. This can result in situations
74where two different processes can return similar or identical keys and
75compromise the security of the system.
76
77The approach this project has chosen to mitigate this vulnerability is to
78include an engine that replaces the OpenSSL default CSPRNG with one that
79sources its entropy from ``/dev/urandom`` on UNIX-like operating systems and
80uses ``CryptGenRandom`` on Windows. This method of pulling from the system pool
81allows us to avoid potential issues with `initializing the RNG`_ as well as
82protecting us from the ``fork()`` weakness.
83
84This engine is **active** by default when importing the OpenSSL backend. When
85active this engine will be used to generate all the random data OpenSSL
86requests.
87
88When importing only the binding it is added to the engine list but
89**not activated**.
90
91
92OS random sources
93-----------------
94
95On macOS and FreeBSD ``/dev/urandom`` is an alias for ``/dev/random``. The
96implementation on macOS uses the `Yarrow`_ algorithm. FreeBSD uses the
97`Fortuna`_ algorithm.
98
99On Windows the implementation of ``CryptGenRandom`` depends on which version of
100the operation system you are using. See the `Microsoft documentation`_ for more
101details.
102
103Linux uses its own PRNG design. ``/dev/urandom`` is a non-blocking source
104seeded from the same pool as ``/dev/random``.
105
106+------------------------------------------+------------------------------+
107| Windows                                  | ``CryptGenRandom()``         |
108+------------------------------------------+------------------------------+
109| Linux >= 3.17 with working               | ``getrandom(GRND_NONBLOCK)`` |
110| ``SYS_getrandom`` syscall                |                              |
111+------------------------------------------+------------------------------+
112| OpenBSD >= 5.6                           | ``getentropy()``             |
113+------------------------------------------+------------------------------+
114| BSD family (including macOS 10.12+) with | ``getentropy()``             |
115| ``SYS_getentropy`` in ``sys/syscall.h``  |                              |
116+------------------------------------------+------------------------------+
117| fallback                                 | ``/dev/urandom`` with        |
118|                                          | cached file descriptor       |
119+------------------------------------------+------------------------------+
120
121
122.. _`OpenSSL`: https://www.openssl.org/
123.. _`initializing the RNG`: https://en.wikipedia.org/wiki/OpenSSL#Predictable_private_keys_.28Debian-specific.29
124.. _`Fortuna`: https://en.wikipedia.org/wiki/Fortuna_(PRNG)
125.. _`Yarrow`: https://en.wikipedia.org/wiki/Yarrow_algorithm
126.. _`Microsoft documentation`: https://docs.microsoft.com/en-us/windows/desktop/api/wincrypt/nf-wincrypt-cryptgenrandom
127