• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. hazmat::
2
3OpenSSL backend
4===============
5
6The `OpenSSL`_ C library. Cryptography supports OpenSSL version 1.1.0 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
71.. note::
72
73    As of OpenSSL 1.1.1d its CSPRNG is fork-safe by default.
74    ``cryptography`` does not compile or load the custom engine on
75    these versions.
76
77By default OpenSSL uses a user-space CSPRNG that is seeded from system random (
78``/dev/urandom`` or ``CryptGenRandom``). This CSPRNG is not reseeded
79automatically when a process calls ``fork()``. This can result in situations
80where two different processes can return similar or identical keys and
81compromise the security of the system.
82
83The approach this project has chosen to mitigate this vulnerability is to
84include an engine that replaces the OpenSSL default CSPRNG with one that
85sources its entropy from ``/dev/urandom`` on UNIX-like operating systems and
86uses ``CryptGenRandom`` on Windows. This method of pulling from the system pool
87allows us to avoid potential issues with `initializing the RNG`_ as well as
88protecting us from the ``fork()`` weakness.
89
90This engine is **active** by default when importing the OpenSSL backend. When
91active this engine will be used to generate all the random data OpenSSL
92requests.
93
94When importing only the binding it is added to the engine list but
95**not activated**.
96
97
98OS random sources
99-----------------
100
101On macOS and FreeBSD ``/dev/urandom`` is an alias for ``/dev/random``. The
102implementation on macOS uses the `Yarrow`_ algorithm. FreeBSD uses the
103`Fortuna`_ algorithm.
104
105On Windows the implementation of ``CryptGenRandom`` depends on which version of
106the operation system you are using. See the `Microsoft documentation`_ for more
107details.
108
109Linux uses its own PRNG design. ``/dev/urandom`` is a non-blocking source
110seeded from the same pool as ``/dev/random``.
111
112+------------------------------------------+------------------------------+
113| Windows                                  | ``CryptGenRandom()``         |
114+------------------------------------------+------------------------------+
115| Linux >= 3.17 with working               | ``getrandom()``              |
116| ``SYS_getrandom`` syscall                |                              |
117+------------------------------------------+------------------------------+
118| OpenBSD >= 5.6                           | ``getentropy()``             |
119+------------------------------------------+------------------------------+
120| BSD family (including macOS 10.12+) with | ``getentropy()``             |
121| ``SYS_getentropy`` in ``sys/syscall.h``  |                              |
122+------------------------------------------+------------------------------+
123| fallback                                 | ``/dev/urandom`` with        |
124|                                          | cached file descriptor       |
125+------------------------------------------+------------------------------+
126
127
128.. _`OpenSSL`: https://www.openssl.org/
129.. _`initializing the RNG`: https://en.wikipedia.org/wiki/OpenSSL#Predictable_private_keys_.28Debian-specific.29
130.. _`Fortuna`: https://en.wikipedia.org/wiki/Fortuna_(PRNG)
131.. _`Yarrow`: https://en.wikipedia.org/wiki/Yarrow_algorithm
132.. _`Microsoft documentation`: https://docs.microsoft.com/en-us/windows/desktop/api/wincrypt/nf-wincrypt-cryptgenrandom
133