rand_lcl.h 9.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258
  1. /*
  2. * Copyright 1995-2018 The OpenSSL Project Authors. All Rights Reserved.
  3. *
  4. * Licensed under the OpenSSL license (the "License"). You may not use
  5. * this file except in compliance with the License. You can obtain a copy
  6. * in the file LICENSE in the source distribution or at
  7. * https://www.openssl.org/source/license.html
  8. */
  9. #ifndef HEADER_RAND_LCL_H
  10. # define HEADER_RAND_LCL_H
  11. # include <openssl/aes.h>
  12. # include <openssl/evp.h>
  13. # include <openssl/sha.h>
  14. # include <openssl/hmac.h>
  15. # include <openssl/ec.h>
  16. # include <openssl/rand_drbg.h>
  17. /* How many times to read the TSC as a randomness source. */
  18. # define TSC_READ_COUNT 4
  19. /* Maximum reseed intervals */
  20. # define MAX_RESEED_INTERVAL (1 << 24)
  21. # define MAX_RESEED_TIME_INTERVAL (1 << 20) /* approx. 12 days */
  22. /* Default reseed intervals */
  23. # define MASTER_RESEED_INTERVAL (1 << 8)
  24. # define SLAVE_RESEED_INTERVAL (1 << 16)
  25. # define MASTER_RESEED_TIME_INTERVAL (60*60) /* 1 hour */
  26. # define SLAVE_RESEED_TIME_INTERVAL (7*60) /* 7 minutes */
  27. /* Max size of additional input and personalization string. */
  28. # define DRBG_MAX_LENGTH 4096
  29. /*
  30. * The quotient between max_{entropy,nonce}len and min_{entropy,nonce}len
  31. *
  32. * The current factor is large enough that the RAND_POOL can store a
  33. * random input which has a lousy entropy rate of 0.0625 bits per byte.
  34. * This input will be sent through the derivation function which 'compresses'
  35. * the low quality input into a high quality output.
  36. */
  37. # define DRBG_MINMAX_FACTOR 128
  38. /* DRBG status values */
  39. typedef enum drbg_status_e {
  40. DRBG_UNINITIALISED,
  41. DRBG_READY,
  42. DRBG_ERROR
  43. } DRBG_STATUS;
  44. /* intantiate */
  45. typedef int (*RAND_DRBG_instantiate_fn)(RAND_DRBG *ctx,
  46. const unsigned char *ent,
  47. size_t entlen,
  48. const unsigned char *nonce,
  49. size_t noncelen,
  50. const unsigned char *pers,
  51. size_t perslen);
  52. /* reseed */
  53. typedef int (*RAND_DRBG_reseed_fn)(RAND_DRBG *ctx,
  54. const unsigned char *ent,
  55. size_t entlen,
  56. const unsigned char *adin,
  57. size_t adinlen);
  58. /* generat output */
  59. typedef int (*RAND_DRBG_generate_fn)(RAND_DRBG *ctx,
  60. unsigned char *out,
  61. size_t outlen,
  62. const unsigned char *adin,
  63. size_t adinlen);
  64. /* uninstantiate */
  65. typedef int (*RAND_DRBG_uninstantiate_fn)(RAND_DRBG *ctx);
  66. /*
  67. * The DRBG methods
  68. */
  69. typedef struct rand_drbg_method_st {
  70. RAND_DRBG_instantiate_fn instantiate;
  71. RAND_DRBG_reseed_fn reseed;
  72. RAND_DRBG_generate_fn generate;
  73. RAND_DRBG_uninstantiate_fn uninstantiate;
  74. } RAND_DRBG_METHOD;
  75. /*
  76. * The state of a DRBG AES-CTR.
  77. */
  78. typedef struct rand_drbg_ctr_st {
  79. EVP_CIPHER_CTX *ctx;
  80. EVP_CIPHER_CTX *ctx_df;
  81. const EVP_CIPHER *cipher;
  82. size_t keylen;
  83. unsigned char K[32];
  84. unsigned char V[16];
  85. /* Temporary block storage used by ctr_df */
  86. unsigned char bltmp[16];
  87. size_t bltmp_pos;
  88. unsigned char KX[48];
  89. } RAND_DRBG_CTR;
  90. /*
  91. * The 'random pool' acts as a dumb container for collecting random
  92. * input from various entropy sources. The pool has no knowledge about
  93. * whether its randomness is fed into a legacy RAND_METHOD via RAND_add()
  94. * or into a new style RAND_DRBG. It is the callers duty to 1) initialize the
  95. * random pool, 2) pass it to the polling callbacks, 3) seed the RNG, and
  96. * 4) cleanup the random pool again.
  97. *
  98. * The random pool contains no locking mechanism because its scope and
  99. * lifetime is intended to be restricted to a single stack frame.
  100. */
  101. struct rand_pool_st {
  102. unsigned char *buffer; /* points to the beginning of the random pool */
  103. size_t len; /* current number of random bytes contained in the pool */
  104. size_t min_len; /* minimum number of random bytes requested */
  105. size_t max_len; /* maximum number of random bytes (allocated buffer size) */
  106. size_t entropy; /* current entropy count in bits */
  107. size_t requested_entropy; /* requested entropy count in bits */
  108. };
  109. /*
  110. * The state of all types of DRBGs, even though we only have CTR mode
  111. * right now.
  112. */
  113. struct rand_drbg_st {
  114. CRYPTO_RWLOCK *lock;
  115. RAND_DRBG *parent;
  116. int secure; /* 1: allocated on the secure heap, 0: otherwise */
  117. int type; /* the nid of the underlying algorithm */
  118. /*
  119. * Stores the value of the rand_fork_count global as of when we last
  120. * reseeded. The DRG reseeds automatically whenever drbg->fork_count !=
  121. * rand_fork_count. Used to provide fork-safety and reseed this DRBG in
  122. * the child process.
  123. */
  124. int fork_count;
  125. unsigned short flags; /* various external flags */
  126. /*
  127. * The random pool is used by RAND_add()/drbg_add() to attach random
  128. * data to the global drbg, such that the rand_drbg_get_entropy() callback
  129. * can pull it during instantiation and reseeding. This is necessary to
  130. * reconcile the different philosophies of the RAND and the RAND_DRBG
  131. * with respect to how randomness is added to the RNG during reseeding
  132. * (see PR #4328).
  133. */
  134. struct rand_pool_st *pool;
  135. /*
  136. * The following parameters are setup by the per-type "init" function.
  137. *
  138. * Currently the only type is CTR_DRBG, its init function is drbg_ctr_init().
  139. *
  140. * The parameters are closely related to the ones described in
  141. * section '10.2.1 CTR_DRBG' of [NIST SP 800-90Ar1], with one
  142. * crucial difference: In the NIST standard, all counts are given
  143. * in bits, whereas in OpenSSL entropy counts are given in bits
  144. * and buffer lengths are given in bytes.
  145. *
  146. * Since this difference has lead to some confusion in the past,
  147. * (see [GitHub Issue #2443], formerly [rt.openssl.org #4055])
  148. * the 'len' suffix has been added to all buffer sizes for
  149. * clarification.
  150. */
  151. int strength;
  152. size_t max_request;
  153. size_t min_entropylen, max_entropylen;
  154. size_t min_noncelen, max_noncelen;
  155. size_t max_perslen, max_adinlen;
  156. /* Counts the number of generate requests since the last reseed. */
  157. unsigned int generate_counter;
  158. /*
  159. * Maximum number of generate requests until a reseed is required.
  160. * This value is ignored if it is zero.
  161. */
  162. unsigned int reseed_interval;
  163. /* Stores the time when the last reseeding occurred */
  164. time_t reseed_time;
  165. /*
  166. * Specifies the maximum time interval (in seconds) between reseeds.
  167. * This value is ignored if it is zero.
  168. */
  169. time_t reseed_time_interval;
  170. /*
  171. * Counts the number of reseeds since instantiation.
  172. * This value is ignored if it is zero.
  173. *
  174. * This counter is used only for seed propagation from the <master> DRBG
  175. * to its two children, the <public> and <private> DRBG. This feature is
  176. * very special and its sole purpose is to ensure that any randomness which
  177. * is added by RAND_add() or RAND_seed() will have an immediate effect on
  178. * the output of RAND_bytes() resp. RAND_priv_bytes().
  179. */
  180. unsigned int reseed_counter;
  181. size_t seedlen;
  182. DRBG_STATUS state;
  183. /* Application data, mainly used in the KATs. */
  184. CRYPTO_EX_DATA ex_data;
  185. /* Implementation specific data (currently only one implementation) */
  186. union {
  187. RAND_DRBG_CTR ctr;
  188. } data;
  189. /* Implementation specific methods */
  190. RAND_DRBG_METHOD *meth;
  191. /* Callback functions. See comments in rand_lib.c */
  192. RAND_DRBG_get_entropy_fn get_entropy;
  193. RAND_DRBG_cleanup_entropy_fn cleanup_entropy;
  194. RAND_DRBG_get_nonce_fn get_nonce;
  195. RAND_DRBG_cleanup_nonce_fn cleanup_nonce;
  196. };
  197. /* The global RAND method, and the global buffer and DRBG instance. */
  198. extern RAND_METHOD rand_meth;
  199. /*
  200. * A "generation count" of forks. Incremented in the child process after a
  201. * fork. Since rand_fork_count is increment-only, and only ever written to in
  202. * the child process of the fork, which is guaranteed to be single-threaded, no
  203. * locking is needed for normal (read) accesses; the rest of pthread fork
  204. * processing is assumed to introduce the necessary memory barriers. Sibling
  205. * children of a given parent will produce duplicate values, but this is not
  206. * problematic because the reseeding process pulls input from the system CSPRNG
  207. * and/or other global sources, so the siblings will end up generating
  208. * different output streams.
  209. */
  210. extern int rand_fork_count;
  211. /* DRBG helpers */
  212. int rand_drbg_restart(RAND_DRBG *drbg,
  213. const unsigned char *buffer, size_t len, size_t entropy);
  214. /* locking api */
  215. int rand_drbg_lock(RAND_DRBG *drbg);
  216. int rand_drbg_unlock(RAND_DRBG *drbg);
  217. int rand_drbg_enable_locking(RAND_DRBG *drbg);
  218. /* initializes the AES-CTR DRBG implementation */
  219. int drbg_ctr_init(RAND_DRBG *drbg);
  220. #endif