Danger
This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns.
OpenSSL backend¶
The OpenSSL C library. Cryptography supports OpenSSL version 1.1.0 and greater.
-
cryptography.hazmat.backends.openssl.
backend
¶ This is the exposed API for the OpenSSL backend.
It implements the following interfaces:
CipherBackend
CMACBackend
DERSerializationBackend
DHBackend
DSABackend
EllipticCurveBackend
HashBackend
HMACBackend
PBKDF2HMACBackend
RSABackend
PEMSerializationBackend
X509Backend
It also implements the following interface for OpenSSL versions
1.1.0
and above.It also exposes the following:
-
name
¶ The string name of this backend:
"openssl"
-
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.
-
openssl_version_number
()¶ New in version 1.8.
Return int: The integer version of the loaded OpenSSL library. This is defined in opensslv.h
asOPENSSL_VERSION_NUMBER
and is typically shown in hexadecimal (e.g.0x1010003f
). This is not necessarily the same version as it was compiled against.
-
activate_osrandom_engine
()¶ Activates the OS random engine. This will effectively disable OpenSSL’s default CSPRNG.
-
osrandom_engine_implementation
()¶ New in version 1.7.
Returns the implementation of OS random engine.
-
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 |