Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RAND_DRBG(7)			    OpenSSL			  RAND_DRBG(7)

NAME
       RAND_DRBG - the deterministic random bit	generator

SYNOPSIS
	#include <openssl/rand_drbg.h>

DESCRIPTION
       The default OpenSSL RAND	method is based	on the RAND_DRBG class,	which
       implements a deterministic random bit generator (DRBG).	A DRBG is a
       certain type of cryptographically-secure	pseudo-random number generator
       (CSPRNG), which is described in [NIST SP	800-90A	Rev. 1].

       While the RAND API is the 'frontend' which is intended to be used by
       application developers for obtaining random bytes, the RAND_DRBG	API
       serves as the 'backend',	connecting the former with the operating
       systems's entropy sources and providing access to the DRBG's
       configuration parameters.

   Disclaimer
       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 Use Cases
       Typical examples	for such special use cases are the following:

       o 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).

       o You need to integrate a previously unsupported	entropy	source.

       o You need to change the	default	settings of the	standard OpenSSL RAND
	 implementation	to meet	specific requirements.

CHAINING
       A DRBG instance can be used as the entropy source of another DRBG
       instance, provided it has itself	access to a valid entropy source.  The
       DRBG instance which acts	as entropy source is called the	parent DRBG,
       the other instance the child DRBG.

       This is called chaining.	A chained DRBG instance	is created by passing
       a pointer to the	parent DRBG as argument	to the RAND_DRBG_new() call.
       It is possible to create	chains of more than two	DRBG in	a row.

THE THREE SHARED DRBG INSTANCES
       Currently, there	are three shared DRBG instances, the <master>,
       <public>, and <private> DRBG.  While the	<master> DRBG is a single
       global instance,	the <public> and <private> DRBG	are created per	thread
       and accessed through thread-local storage.

       By default, the functions RAND_bytes(3) and RAND_priv_bytes(3) use the
       thread-local <public> and <private> DRBG	instance, respectively.

   The <master>	DRBG instance
       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).

   The <public>	DRBG instance
       This instance is	used per default by RAND_bytes(3).

   The <private> DRBG instance
       This instance is	used per default by RAND_priv_bytes(3)

LOCKING
       The <master> DRBG is intended to	be accessed concurrently for reseeding
       by its child DRBG instances. The	necessary locking is done internally.
       It is not thread-safe to	access the <master> DRBG directly via the
       RAND_DRBG interface.  The <public> and <private>	DRBG are thread-local,
       i.e. there is an	instance of each per thread. So	they can safely	be
       accessed	without	locking	via the	RAND_DRBG interface.

       Pointers	to these DRBG instances	can be obtained	using
       RAND_DRBG_get0_master(),	RAND_DRBG_get0_public(), and
       RAND_DRBG_get0_private(), respectively.	Note that it is	not allowed to
       store a pointer to one of the thread-local DRBG instances in a variable
       or other	memory location	where it will be accessed and used by multiple
       threads.

       All other DRBG instances	created	by an application don't	support
       locking,	because	they are intended to be	used by	a single thread.
       Instead of accessing a single DRBG instance concurrently	from different
       threads,	it is recommended to instantiate a separate DRBG instance per
       thread. Using the <master> DRBG as entropy source for multiple DRBG
       instances on different threads is thread-safe, because the DRBG
       instance	will lock the <master> DRBG automatically for obtaining	random
       input.

THE OVERALL PICTURE
       The following picture gives an overview over how	the DRBG instances
       work together and are being used.

		      +--------------------+
		      |	os entropy sources |
		      +--------------------+
			       |
			       v	   +-----------------------------+
	     RAND_add()	==> <master>	 <-| shared DRBG (with locking)	 |
			     /	 \	   +-----------------------------+
			    /	  \		 +---------------------------+
		     <public>	  <private>   <- | per-thread DRBG instances |
			|	      |		 +---------------------------+
			v	      v
		      RAND_bytes()   RAND_priv_bytes()
			   |		   ^
			   |		   |
	   +------------------+	     +------------------------------------+
	   | general purpose  |	     | used for	secrets	like session keys |
	   | random generator |	     | and private keys	for certificates  |
	   +------------------+	     +------------------------------------+

       The usual way to	obtain random bytes is to call RAND_bytes(...) or
       RAND_priv_bytes(...). These calls are roughly equivalent	to calling
       RAND_DRBG_bytes(<public>, ...) and RAND_DRBG_bytes(<private>, ...),
       respectively. The method	RAND_DRBG_bytes(3) is a	convenience method
       wrapping	the RAND_DRBG_generate(3) function, which serves the actual
       request for random data.

RESEEDING
       A DRBG instance seeds itself automatically, pulling random input	from
       its entropy source. The entropy source can be either a trusted
       operating system	entropy	source,	or another DRBG	with access to such a
       source.

       Automatic reseeding occurs after	a predefined number of generate
       requests.  The selection	of the trusted entropy sources is configured
       at build	time using the --with-rand-seed	option.	The following sections
       explain the reseeding process in	more detail.

   Automatic Reseeding
       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.

   Manual Reseeding
       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().

   Entropy Input vs. Additional	Data
       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).

   Configuring the Random Seed Source
       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.

   Reseeding the master	DRBG with automatic seeding enabled
       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.

   Reseeding the master	DRBG with automatic seeding disabled
       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.

SEE ALSO
       RAND_DRBG_bytes(3), RAND_DRBG_generate(3), RAND_DRBG_reseed(3),
       RAND_DRBG_get0_master(3), RAND_DRBG_get0_public(3),
       RAND_DRBG_get0_private(3), RAND_DRBG_set_reseed_interval(3),
       RAND_DRBG_set_reseed_time_interval(3),
       RAND_DRBG_set_reseed_defaults(3), RAND(7),

COPYRIGHT
       Copyright 2017-2018 The OpenSSL Project Authors.	All Rights Reserved.

       Licensed	under the OpenSSL license (the "License").  You	may not	use
       this file except	in compliance with the License.	 You can obtain	a copy
       in the file LICENSE in the source distribution or at
       <https://www.openssl.org/source/license.html>.

1.1.1k				  2021-03-25			  RAND_DRBG(7)

NAME | SYNOPSIS | DESCRIPTION | CHAINING | THE THREE SHARED DRBG INSTANCES | LOCKING | THE OVERALL PICTURE | RESEEDING | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=RAND_DRBG&sektion=7&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help