Manpages - RAND_DRBG.7ssl

Unless you have very specific requirements for your random generator, it is in general not necessary to utilize the RAND_DRBG API directly. The usual way to obtain random bytes is to use RAND_bytes (3) or RAND_priv_bytes (3), see also RAND (7).

Typical examples for such special use cases are the following:

• You want to use your own private DRBG instances. Multiple DRBG instances which are accessed only by a single thread provide additional security (because their internal states are independent) and better scalability in multithreaded applications (because they don’t need to be locked).
• You need to integrate a previously unsupported entropy source.
• You need to change the default settings of the standard OpenSSL RAND implementation to meet specific requirements.

The <master> DRBG is not used directly by the application, only for reseeding the two other two DRBG instances. It reseeds itself by obtaining randomness either from os entropy sources or by consuming randomness which was added previously by RAND_add (3).

This instance is used per default by RAND_bytes (3).

This instance is used per default by RAND_priv_bytes (3)

Before satisfying a generate request (RAND_DRBG_generate (3)), the DRBG reseeds itself automatically, if one of the following conditions holds:

• the DRBG was not instantiated (=seeded) yet or has been

uninstantiated.

• the number of generate requests since the last reseeding exceeds a

certain threshold, the so called reseed_interval. This behaviour can be disabled by setting the reseed_interval to 0.

• the time elapsed since the last reseeding exceeds a certain time

interval, the so called reseed_time_interval. This can be disabled by setting the reseed_time_interval to 0.

• the DRBG is in an error state.

Note: An error state is entered if the entropy source fails while the DRBG is seeding or reseeding. The last case ensures that the DRBG automatically recovers from the error as soon as the entropy source is available again.

In addition to automatic reseeding, the caller can request an immediate reseeding of the DRBG with fresh entropy by setting the prediction resistance parameter to 1 when calling RAND_DRBG_generate (3).

The document [NIST SP 800-90C] describes prediction resistance requests in detail and imposes strict conditions on the entropy sources that are approved for providing prediction resistance. Since the default DRBG implementation does not have access to such an approved entropy source, a request for prediction resistance will currently always fail. In other words, prediction resistance is currently not supported yet by the DRBG.

For the three shared DRBGs (and only for these) there is another way to reseed them manually: If RAND_add (3) is called with a positive randomness argument (or RAND_seed (3)), then this will immediately reseed the <master> DRBG. The <public> and <private> DRBG will detect this on their next generate call and reseed, pulling randomness from <master>.

The last feature has been added to support the common practice used with previous OpenSSL versions to call RAND_add() before calling RAND_bytes().

The DRBG distinguishes two different types of random input: entropy, which comes from a trusted source, and additional input’, which can optionally be added by the user and is considered untrusted. It is possible to add additional input not only during reseeding, but also for every generate request. This is in fact done automatically by RAND_DRBG_bytes (3).

In most cases OpenSSL will automatically choose a suitable seed source for automatically seeding and reseeding its <master> DRBG. In some cases however, it will be necessary to explicitly specify a seed source during configuration, using the –with-rand-seed option. For more information, see the INSTALL instructions. There are also operating systems where no seed source is available and automatic reseeding is disabled by default.

The following two sections describe the reseeding process of the master DRBG, depending on whether automatic reseeding is available or not.

Calling RAND_poll() or RAND_add() is not necessary, because the DRBG pulls the necessary entropy from its source automatically. However, both calls are permitted, and do reseed the RNG.

RAND_add() can be used to add both kinds of random input, depending on the value of the randomness argument:

randomness == 0:

The random bytes are mixed as additional input into the current state of the DRBG. Mixing in additional input is not considered a full reseeding, hence the reseed counter is not reset.

randomness > 0:

The random bytes are used as entropy input for a full reseeding (resp. reinstantiation) if the DRBG is instantiated (resp. uninstantiated or in an error state). The number of random bits required for reseeding is determined by the security strength of the DRBG. Currently it defaults to 256 bits (32 bytes). It is possible to provide less randomness than required. In this case the missing randomness will be obtained by pulling random input from the trusted entropy sources.

Calling RAND_poll() will always fail.

RAND_add() needs to be called for initial seeding and periodic reseeding. At least 48 bytes (384 bits) of randomness have to be provided, otherwise the (re-)seeding of the DRBG will fail. This corresponds to one and a half times the security strength of the DRBG. The extra half is used for the nonce during instantiation.

More precisely, the number of bytes needed for seeding depend on the security strength of the DRBG, which is set to 256 by default.