Use of OpenSSL¶
cryptography depends on the OpenSSL C library for all cryptographic
operation. OpenSSL is the de facto standard for cryptographic libraries and
provides high performance along with various certifications that may be
relevant to developers.
A list of supported versions can be found in our Installation documentation.
In general the backend should be considered an internal implementation detail of the project, but there are some public methods available for more advanced control.
- Return text
The friendly string name of the loaded OpenSSL library. This is not necessarily the same version as it was compiled against.
New in version 1.8.
- Return int
The integer version of the loaded OpenSSL library. This is defined in
OPENSSL_VERSION_NUMBERand is typically shown in hexadecimal (e.g.
0x1010003f). This is not necessarily the same version as it was compiled against.
Activates the OS random engine. This will effectively disable OpenSSL’s default CSPRNG.
New in version 1.7.
Returns the implementation of OS random engine.
This will activate the default OpenSSL CSPRNG.
Legacy provider in OpenSSL 3.x¶
New in version 39.0.0.
Users can set
CRYPTOGRAPHY_OPENSSL_NO_LEGACY environment variable to
disable the legacy provider in OpenSSL 3.x. This will disable legacy
cryptographic algorithms, including
RC2 (which is used by some encrypted serialization formats).
OS random engine¶
As of OpenSSL 1.1.1d its CSPRNG is fork-safe by default.
cryptography does not compile or load the custom engine on
By default OpenSSL uses a user-space CSPRNG that is seeded from system random (
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
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
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 Windows the implementation of
CryptGenRandom depends on which version of
the operation system you are using. See the Microsoft documentation for more
Linux uses its own PRNG design.
/dev/urandom is a non-blocking source
seeded from the same pool as
Linux >= 3.17 with working
OpenBSD >= 5.6
BSD family (including macOS 10.12+) with