ESDM

… or /dev/random in user space

The Entropy Source and DRNG Manager (ESDM) manages a set of deterministic random number generators (DRNG) and ensures their proper seeding and reseeding. To seed the DRNGs, a set of entropy sources are managed by the ESDM. The cryptographic strength of the entire ESDM is always 256 bits. All entropy processing is designed to maintain this strength.

Besides other services, it provides an API and ABI compliant drop-in replacement for the Linux /dev/random and /dev/urandom devices as well as the getrandom system call. This means it not only supports common users requesting random numbers, but also services using the IOCTLs documented in random(4) or using select(2) / poll(2) on the device files.

In addition to the Linux interface support, the ESDM provides a daemon managing the entropy sources and DRNG instances that can be accessed with a wrapper library. The ESDM requires only POSIX support along with protobuf-c and thus is intended to be executable on different operating systems.

It is extensible as follows:

  • Additional entropy sources can easily be added, existing entropy sources can be deselected during compile time or its entropy rate altered during startup time.

  • The cryptographic primitives can be altered by simply providing a new backend for hash algorithms or DRNG algorithms. See the drng_chacha20 configuration option replacing the SP800-90A DRBG with a ChaCha20-based DRNG, or the hash_sha3_512 configuration option replacing the SHA2-512 conditioning hash with SHA3-512.

  • Different DRNG Seeding strategies can be defined, by modifying one location in the code that governs the initial and reseeding operation of the DRNGs.

The (re)seeding operation of the DRNG implements design ideas of the following specifications:

  • SP800-90B: The entropy source of the Jitter RNG provides an SP800-90B compliant entropy source. In addition, the Intel RDSEED instruction is claimed to provide an SP800-90B entropy source. Also, when using the scheduler-based entropy source - which is only implemented for the Linux kernel using the code in addon/linux_esdm_es, a separate SP800-90B entropy source is provided. In addition, when using the interrupt-based entropy source - which is only implemented for the Linux kernel using the code in addon/linux_esdm_es, a separate SP800-90B entropy source is provided. If the kernel-based jitter entropy source shall be used, please compile your Linux kernel with CONFIG_CRYPTO_JITTERENTROPY.

  • SP800-90C: The specification provides guidelines how to combine a DRNG and entropy sources.

Build

Use the Meson/Ninja build infrastructure with the following steps:

  1. meson setup build

  2. meson compile -C build

  3. meson install -C build

Dependencies

The following dependencies are required:

  • protobuf-c: When enabling any code beyond the ESDM library, the protobuf-c support is needed. Either the package of your favorite distribution must be installed or obtain the sources from the Protobuf-C Github website.

The following dependencies are required provided the respective functionality is enabled during compile time:

  • Jitter RNG: If the Jitter RNG entropy source is enabled as a compile time option, install the Jitter RNG library from your distribution or from the Jitter RNG homepage.

  • kcapi library: If the kernel-based jitter source is enabled as a compile time option, the kcapi library is required, either from your distribution or from the libkcapi website.

  • SELinux library: If your system uses SELinux and you compile the CUSE device file support (compile time option), the SELinux library is needed for proper device file labeling. In this case, use the package from your distribution.

  • FUSE 3 library: If the CUSE daemons shall be compiled and are enabled as a compile time option, the FUSE 3 library is required either from your distribution or from the libfuse Github website.

  • Botan >= 3.0: If the Botan backend for cryptographic operations shall be used and is enabled as a compile time option, or if the Botan ESDM seed source shall be compiled when the compile time option is enabled get Botan either from your distribution or from the botan Github website.

  • OpenSSL >= 3.0: If the OpenSSL backend for cryptographic operations shall be used and is enabled as a compile time option, or if the OpenSSL ESDM seed source shall be compiled when the compile time option is enabled, obtain OpenSSL either from your distribution or from the OpenSSL website.

  • leancrypto: If the leancrypto backend for cryptographic operations shall be enabled during compile time, obtain leancrypto from the leancrypto website.

Beyond those dependencies, only POSIX support is required.

A public git repository is provided with Github

Documentation

The reference to the applicable documentation is given with the various releases.

Subsections of ESDM

ESDM 1.2.0

ESDM Source Code

ESDM Source Code Signature

Documentation

The following documentation is available:

Changelog

  • fix: to prevent a DoS against the RPC channel, limit the slow operations of esdm_get_random_bytes_pr and esdm_get_seed to allow only one call in flight. If another call comes in while one process is ongoing, return -EAGAIN to free the RPC channel.

  • fix: handle rogue libesdm-aux clients more gracefully - if a client received a notification to supply entropy, but it fails to send anything, the ESDM will not send a notification again. This issue is alleviated by checking the need_entropy common variable

  • switch from CLOCK_REALTIME to CLOCK_MONOTONIC for wait operations

  • add esdm.spec file for generating an RPM

Standards Compliance

  • SP800-90A/B/C compliant

  • AIS20/31 2011 compliant

  • AIS20/31 draft 2022 compliant

  • FIPS IG 7.19 / D.K compliant - use of DRBG as conditioning component for chaining DRBGs

ESDM 1.1.1

ESDM Source Code

ESDM Source Code_Signature

Documentation

The following documentation is available:

Changelog

  • fix: properly use the mutex absolute time argument, timedlock handling and mutex destruction in the ESDM RPC client lib

  • fix: race condition in worker thread execution

Standards Compliance

  • SP800-90A/B/C compliant

  • AIS20/31 2011 compliant

  • AIS20/31 draft 2022 compliant

  • FIPS IG 7.19 / D.K compliant - use of DRBG as conditioning component for chaining DRBGs

ESDM 1.1.0

ESDM Source Code

ESDM Source Code_Signature

Documentation

The following documentation is available:

Changelog

  • fix: name of leancrypto DRNG

  • fix: getentropy returns 0 on success

  • enhancement: only establish connection to server once and when needed

  • fix: SHM in CUSE must be attached RD/WR

  • enhancement: add esdm_aux_client library

Standards Compliance

  • SP800-90A/B/C compliant

  • AIS20/31 2011 compliant

  • AIS20/31 draft 2022 compliant

  • FIPS IG 7.19 / D.K compliant - use of DRBG as conditioning component for chaining DRBGs

ESDM 1.0.2

ESDM Source Code

ESDM Source Code_Signature

Documentation

The following documentation is available:

Changelog

  • hardening: enable -fzero-call-used-regs=used-gpr

  • editorial: rename logging* symbols to esdm_logging* - this is purely internal, but considering some of these symbols are externally visible, libesdm_rpc_client pollutes the namespace of consumers

  • enhancement: significant performance increase of RPC communication

  • fix: Poll writer woke up as status variable was not properly initialized

  • fix: proper shut down sequence of ESDM daemons

Standards Compliance

  • SP800-90A/B/C compliant

  • AIS20/31 2011 compliant

  • AIS20/31 draft 2022 compliant

  • FIPS IG 7.19 / D.K compliant - use of DRBG as conditioning component for chaining DRBGs

ESDM 1.0.1

ESDM Source Code

ESDM Source Code_Signature

Documentation

The following documentation is available:

Changelog

  • enhancement/fix: add support for multiple ESDM RPC client connection initializations

  • fix: If a process select/poll on a CUSE file, the system now goes properly to sleep

  • fix: If there is high load on the CUSE daemons - make sure they properly shut down on reboot

Standards Compliance

  • SP800-90A/B/C compliant

  • AIS20/31 2011 compliant

  • AIS20/31 draft 2022 compliant

  • FIPS IG 7.19 / D.K compliant - use of DRBG as conditioning component for chaining DRBGs

ESDM 1.0.0

ESDM Source Code

ESDM Source Code_Signature

Documentation

The following documentation is available:

Changelog

  • IRQ/Sched ES: add support to retry accessing the kernel with -i and -s flags

  • enhancement: Jitter RNG ES generates data asynchronously

  • enhancement: add kernel Jitter RNG ES

  • enhancement: add leancrypto, OpenSSL and Botan crypto provider backends

  • enhancement: add OpenSSL, Botan seed provider (leancrypto ESDM seed provider is found in leancrypto source code)

  • fix: ESDM server - systemd unit executes server in current mount namespace

  • editorial: apply clang-format

  • fix: CUSE daemons may hang during shutdown due to busy mounts

  • fix: resynchronize CUSE daemons and ESDM server upon ESDM server restart

  • enhancement: ESDM server status splits up FIPS 140 and SP800-90C compliance

  • rename compile time option “oversample_es” to “sp80090c” which is now disabled by default considering that with its enabling, the oversampling is applied unconditionally during startup

Standards Compliance

  • SP800-90A/B/C compliant

  • AIS20/31 2011 compliant

  • AIS20/31 draft 2022 compliant

  • FIPS IG 7.19 / D.K compliant - use of DRBG as conditioning component for chaining DRBGs

ESDM 0.6.0

ESDM Source Code

ESDM Source Code_Signature

Documentation

The following documentation is available:

Changelog

  • Move ESDM apps into separate namespaces to limit their privilege even further (e.g. no possibility to create network connections)

  • Add German AIS 20/31 (draft 2022) NTG.1 compliance support

  • the blocking property of an interface is implemented in the client - the server reports -EAGAIN for a blocking behavior

  • add “emergency seeding” when entropy sources cannot collectively deliver 256 bits of entropy, pull data repeatedly until 256 bits are received

  • export esdm_rpc_client.h with all depending header files to allow external clients to be developed

  • update IRQ/Scheduler ES health test to match LRNG

  • bug fix: correctly calculate memory offsets

  • enhancement: Sched/IRQ ES code in ESDM can handle if kernel-parts have different data structure size for sending entropy to user space

  • IRQ/Sched ES: Switch to /dev/esdm_es character devices a user space interfaces

  • fix of deadlocks during shutdown

Standards Compliance

  • SP800-90A/B/C compliant

  • AIS20/31 2011 compliant

  • AIS20/31 draft 2022 compliant

  • FIPS IG 7.19 / D.K compliant - use of DRBG as conditioning component for chaining DRBGs

ESDM 0.5.0

ESDM Source Code

ESDM Source Code_Signature

Documentation

The following documentation is available:

Changelog

  • Linux kernel entropy feeder is now always enabled

  • Add Linux /dev/hwrng entropy source

  • FIPS IG 7.19/D.K / BSI NTG.1: use a new DRNG instance executed with PR

  • Handle communication errors between client and server gracefully

  • ES monitor now runs for lifetime of the ESDM

  • add interface to access entropy sources - esdm_get_seed including making it accessible via getrandom(2)

  • fix of deadlocks during shutdown

Standards Compliance

  • SP800-90A/B/C compliant

  • AIS20/31 2011 compliant

  • FIPS IG 7.19 / D.K compliant - use of DRBG as conditioning component for chaining DRBGs

ESDM 0.4.0

ESDM Source Code

ESDM Source Code_Signature

Documentation

The following documentation is available:

Changelog

  • Start CUSE daemons independently from ESDM server

  • add support for invoking DRNG with prediction resistance when opening /dev/random with O_SYNC or using the esdm_get_random_bytes_pr API. This reestablishes the NTG.1 property as well as well as supports using the DRBG as a conditioning component pursuent to SP800-90C and FIPS 140 IG 7.19 / D.K.

  • initialize the DRNG immediately with 256 bits (disregarding 32/128 bits)

  • add interrupt entropy source

  • modify collection in scheduler ES: maintain a hash state per CPU as a per-CPU entropy pool

  • add proper interrupt/signal handling code to the ESDM RPC client library

  • privilege level change in CUSE is now limited to caller only

  • add support to allow ld.so.preload to be used to refer to libesdm-getrandom.so for a system-wide replacement of getrandom/getentropy system call.

Standards Compliance

  • SP800-90A/B/C compliant

  • AIS20/31 2011 compliant

  • FIPS IG 7.19 / D.K compliant - use of DRBG as conditioning component for chaining DRBGs

ESDM 0.3.0

ESDM Source Code

ESDM Source Code_Signature

Changelog

  • Testing: disable /dev/random fallbacks for verifying RPC operation

  • RNDGETENTCNT returns the seed state of the auxiliary entropy pool only. This makes it 100% ABI compliant to random.c

  • Add ChaCha20 DRNG to regular code base

  • Add SHA-3 conditioning hash to regular code base

  • Add /proc/sys/kernel/random files handler along with SELinux policy, tested with: rng-tools, jitterentropy-rngd, haveged

Standards Compliance

  • SP800-90A/B/C compliant