RAND_DRBG.pod 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301
  1. =pod
  2. =head1 NAME
  3. RAND_DRBG - the deterministic random bit generator
  4. =head1 SYNOPSIS
  5. #include <openssl/rand_drbg.h>
  6. =head1 DESCRIPTION
  7. The default OpenSSL RAND method is based on the RAND_DRBG class,
  8. which implements a deterministic random bit generator (DRBG).
  9. A DRBG is a certain type of cryptographically-secure pseudo-random
  10. number generator (CSPRNG), which is described in
  11. [NIST SP 800-90A Rev. 1].
  12. While the RAND API is the 'frontend' which is intended to be used by
  13. application developers for obtaining random bytes, the RAND_DRBG API
  14. serves as the 'backend', connecting the former with the operating
  15. systems's entropy sources and providing access to the DRBG's
  16. configuration parameters.
  17. =head2 Disclaimer
  18. Unless you have very specific requirements for your random generator,
  19. it is in general not necessary to utilize the RAND_DRBG API directly.
  20. The usual way to obtain random bytes is to use L<RAND_bytes(3)> or
  21. L<RAND_priv_bytes(3)>, see also L<RAND(7)>.
  22. =head2 Typical Use Cases
  23. Typical examples for such special use cases are the following:
  24. =over 2
  25. =item *
  26. You want to use your own private DRBG instances.
  27. Multiple DRBG instances which are accessed only by a single thread provide
  28. additional security (because their internal states are independent) and
  29. better scalability in multithreaded applications (because they don't need
  30. to be locked).
  31. =item *
  32. You need to integrate a previously unsupported entropy source.
  33. =item *
  34. You need to change the default settings of the standard OpenSSL RAND
  35. implementation to meet specific requirements.
  36. =back
  37. =head1 CHAINING
  38. A DRBG instance can be used as the entropy source of another DRBG instance,
  39. provided it has itself access to a valid entropy source.
  40. The DRBG instance which acts as entropy source is called the I<parent> DRBG,
  41. the other instance the I<child> DRBG.
  42. This is called chaining. A chained DRBG instance is created by passing
  43. a pointer to the parent DRBG as argument to the RAND_DRBG_new() call.
  44. It is possible to create chains of more than two DRBG in a row.
  45. =head1 THE THREE SHARED DRBG INSTANCES
  46. Currently, there are three shared DRBG instances,
  47. the <master>, <public>, and <private> DRBG.
  48. While the <master> DRBG is a single global instance, the <public> and <private>
  49. DRBG are created per thread and accessed through thread-local storage.
  50. By default, the functions L<RAND_bytes(3)> and L<RAND_priv_bytes(3)> use
  51. the thread-local <public> and <private> DRBG instance, respectively.
  52. =head2 The <master> DRBG instance
  53. The <master> DRBG is not used directly by the application, only for reseeding
  54. the two other two DRBG instances. It reseeds itself by obtaining randomness
  55. either from os entropy sources or by consuming randomness which was added
  56. previously by L<RAND_add(3)>.
  57. =head2 The <public> DRBG instance
  58. This instance is used per default by L<RAND_bytes(3)>.
  59. =head2 The <private> DRBG instance
  60. This instance is used per default by L<RAND_priv_bytes(3)>
  61. =head1 LOCKING
  62. The <master> DRBG is intended to be accessed concurrently for reseeding
  63. by its child DRBG instances. The necessary locking is done internally.
  64. It is I<not> thread-safe to access the <master> DRBG directly via the
  65. RAND_DRBG interface.
  66. The <public> and <private> DRBG are thread-local, i.e. there is an
  67. instance of each per thread. So they can safely be accessed without
  68. locking via the RAND_DRBG interface.
  69. Pointers to these DRBG instances can be obtained using
  70. RAND_DRBG_get0_master(),
  71. RAND_DRBG_get0_public(), and
  72. RAND_DRBG_get0_private(), respectively.
  73. Note that it is not allowed to store a pointer to one of the thread-local
  74. DRBG instances in a variable or other memory location where it will be
  75. accessed and used by multiple threads.
  76. All other DRBG instances created by an application don't support locking,
  77. because they are intended to be used by a single thread.
  78. Instead of accessing a single DRBG instance concurrently from different
  79. threads, it is recommended to instantiate a separate DRBG instance per
  80. thread. Using the <master> DRBG as entropy source for multiple DRBG
  81. instances on different threads is thread-safe, because the DRBG instance
  82. will lock the <master> DRBG automatically for obtaining random input.
  83. =head1 THE OVERALL PICTURE
  84. The following picture gives an overview over how the DRBG instances work
  85. together and are being used.
  86. +--------------------+
  87. | os entropy sources |
  88. +--------------------+
  89. |
  90. v +-----------------------------+
  91. RAND_add() ==> <master> <-| shared DRBG (with locking) |
  92. / \ +-----------------------------+
  93. / \ +---------------------------+
  94. <public> <private> <- | per-thread DRBG instances |
  95. | | +---------------------------+
  96. v v
  97. RAND_bytes() RAND_priv_bytes()
  98. | ^
  99. | |
  100. +------------------+ +------------------------------------+
  101. | general purpose | | used for secrets like session keys |
  102. | random generator | | and private keys for certificates |
  103. +------------------+ +------------------------------------+
  104. The usual way to obtain random bytes is to call RAND_bytes(...) or
  105. RAND_priv_bytes(...). These calls are roughly equivalent to calling
  106. RAND_DRBG_bytes(<public>, ...) and RAND_DRBG_bytes(<private>, ...),
  107. respectively. The method L<RAND_DRBG_bytes(3)> is a convenience method
  108. wrapping the L<RAND_DRBG_generate(3)> function, which serves the actual
  109. request for random data.
  110. =head1 RESEEDING
  111. A DRBG instance seeds itself automatically, pulling random input from
  112. its entropy source. The entropy source can be either a trusted operating
  113. system entropy source, or another DRBG with access to such a source.
  114. Automatic reseeding occurs after a predefined number of generate requests.
  115. The selection of the trusted entropy sources is configured at build
  116. time using the --with-rand-seed option. The following sections explain
  117. the reseeding process in more detail.
  118. =head2 Automatic Reseeding
  119. Before satisfying a generate request (L<RAND_DRBG_generate(3)>), the DRBG
  120. reseeds itself automatically, if one of the following conditions holds:
  121. - the DRBG was not instantiated (=seeded) yet or has been uninstantiated.
  122. - the number of generate requests since the last reseeding exceeds a
  123. certain threshold, the so called I<reseed_interval>.
  124. This behaviour can be disabled by setting the I<reseed_interval> to 0.
  125. - the time elapsed since the last reseeding exceeds a certain time
  126. interval, the so called I<reseed_time_interval>.
  127. This can be disabled by setting the I<reseed_time_interval> to 0.
  128. - the DRBG is in an error state.
  129. B<Note>: An error state is entered if the entropy source fails while
  130. the DRBG is seeding or reseeding.
  131. The last case ensures that the DRBG automatically recovers
  132. from the error as soon as the entropy source is available again.
  133. =head2 Manual Reseeding
  134. In addition to automatic reseeding, the caller can request an immediate
  135. reseeding of the DRBG with fresh entropy by setting the
  136. I<prediction resistance> parameter to 1 when calling L<RAND_DRBG_generate(3)>.
  137. The dcoument [NIST SP 800-90C] describes prediction resistance requests
  138. in detail and imposes strict conditions on the entropy sources that are
  139. approved for providing prediction resistance.
  140. Since the default DRBG implementation does not have access to such an approved
  141. entropy source, a request for prediction resistance will currently always fail.
  142. In other words, prediction resistance is currently not supported yet by the DRBG.
  143. For the three shared DRBGs (and only for these) there is another way to
  144. reseed them manually:
  145. If L<RAND_add(3)> is called with a positive I<randomness> argument
  146. (or L<RAND_seed(3)>), then this will immediately reseed the <master> DRBG.
  147. The <public> and <private> DRBG will detect this on their next generate
  148. call and reseed, pulling randomness from <master>.
  149. The last feature has been added to support the common practice used with
  150. previous OpenSSL versions to call RAND_add() before calling RAND_bytes().
  151. =head2 Entropy Input vs. Additional Data
  152. The DRBG distinguishes two different types of random input: I<entropy>,
  153. which comes from a trusted source, and I<additional input>',
  154. which can optionally be added by the user and is considered untrusted.
  155. It is possible to add I<additional input> not only during reseeding,
  156. but also for every generate request.
  157. This is in fact done automatically by L<RAND_DRBG_bytes(3)>.
  158. =head2 Configuring the Random Seed Source
  159. In most cases OpenSSL will automatically choose a suitable seed source
  160. for automatically seeding and reseeding its <master> DRBG. In some cases
  161. however, it will be necessary to explicitely specify a seed source during
  162. configuration, using the --with-rand-seed option. For more information,
  163. see the INSTALL instructions. There are also operating systems where no
  164. seed source is available and automatic reseeding is disabled by default.
  165. The following two sections describe the reseeding process of the master
  166. DRBG, depending on whether automatic reseeding is available or not.
  167. =head2 Reseeding the master DRBG with automatic seeding enabled
  168. Calling RAND_poll() or RAND_add() is not necessary, because the DRBG
  169. pulls the necessary entropy from its source automatically.
  170. However, both calls are permitted, and do reseed the RNG.
  171. RAND_add() can be used to add both kinds of random input, depending on the
  172. value of the B<randomness> argument:
  173. =over 4
  174. =item randomness == 0:
  175. The random bytes are mixed as additional input into the current state of
  176. the DRBG.
  177. Mixing in additional input is not considered a full reseeding, hence the
  178. reseed counter is not reset.
  179. =item randomness > 0:
  180. The random bytes are used as entropy input for a full reseeding
  181. (resp. reinstantiation) if the DRBG is instantiated
  182. (resp. uninstantiated or in an error state).
  183. The number of random bits required for reseeding is determined by the
  184. security strength of the DRBG. Currently it defaults to 256 bits (32 bytes).
  185. It is possible to provide less randomness than required.
  186. In this case the missing randomness will be obtained by pulling random input
  187. from the trusted entropy sources.
  188. =back
  189. =head2 Reseeding the master DRBG with automatic seeding disabled
  190. Calling RAND_poll() will always fail.
  191. RAND_add() needs to be called for initial seeding and periodic reseeding.
  192. At least 48 bytes (384 bits) of randomness have to be provided, otherwise
  193. the (re-)seeding of the DRBG will fail. This corresponds to one and a half
  194. times the security strength of the DRBG. The extra half is used for the
  195. nonce during instantiation.
  196. More precisely, the number of bytes needed for seeding depend on the
  197. I<security strength> of the DRBG, which is set to 256 by default.
  198. =head1 SEE ALSO
  199. L<RAND_DRBG_bytes(3)>,
  200. L<RAND_DRBG_generate(3)>,
  201. L<RAND_DRBG_reseed(3)>,
  202. L<RAND_DRBG_get0_master(3)>,
  203. L<RAND_DRBG_get0_public(3)>,
  204. L<RAND_DRBG_get0_private(3)>,
  205. L<RAND_DRBG_set_reseed_interval(3)>,
  206. L<RAND_DRBG_set_reseed_time_interval(3)>,
  207. L<RAND_DRBG_set_reseed_defaults(3)>,
  208. L<RAND(7)>,
  209. =head1 COPYRIGHT
  210. Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
  211. Licensed under the OpenSSL license (the "License"). You may not use
  212. this file except in compliance with the License. You can obtain a copy
  213. in the file LICENSE in the source distribution or at
  214. L<https://www.openssl.org/source/license.html>.
  215. =cut