src/lib/crypt_ops/crypto_rand.h

   1 /* Copyright (c) 2001, Matej Pfajfar.
   2  * Copyright (c) 2001-2004, Roger Dingledine.
   3  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
   4  * Copyright (c) 2007-2021, The Tor Project, Inc. */
   5 /* See LICENSE for licensing information */
   6
   7 /**
   8  * \file crypto_rand.h
   9  *
  10  * \brief Common functions for using (pseudo-)random number generators.
  11  **/
  12
  13 #ifndef TOR_CRYPTO_RAND_H
  14 #define TOR_CRYPTO_RAND_H
  15
  16 #include "lib/cc/compat_compiler.h"
  17 #include "lib/cc/torint.h"
  18 #include "lib/testsupport/testsupport.h"
  19 #include "lib/malloc/malloc.h"
  20
  21 /* random numbers */
  22 int crypto_seed_rng(void) ATTR_WUR;
  23 MOCK_DECL(void,crypto_rand,(char *to, size_t n));
  24 void crypto_rand_unmocked(char *to, size_t n);
  25 void crypto_strongest_rand(uint8_t *out, size_t out_len);
  26 MOCK_DECL(void,crypto_strongest_rand_,(uint8_t *out, size_t out_len));
  27 int crypto_rand_int(unsigned int max);
  28 unsigned crypto_rand_uint(unsigned limit);
  29 int crypto_rand_int_range(unsigned int min, unsigned int max);
  30 uint64_t crypto_rand_uint64_range(uint64_t min, uint64_t max);
  31 time_t crypto_rand_time_range(time_t min, time_t max);
  32 uint32_t crypto_rand_u32(void);
  33 uint64_t crypto_rand_uint64(uint64_t max);
  34 double crypto_rand_double(void);
  35 struct tor_weak_rng_t;
  36 void crypto_seed_weak_rng(struct tor_weak_rng_t *rng);
  37
  38 char *crypto_random_hostname(int min_rand_len, int max_rand_len,
  39                              const char *prefix, const char *suffix);
  40
  41 struct smartlist_t;
  42 void *smartlist_choose(const struct smartlist_t *sl);
  43 void smartlist_shuffle(struct smartlist_t *sl);
  44 int crypto_force_rand_ssleay(void);
  45
  46 /**
  47  * A fast PRNG, for use when the PRNG provided by our crypto library isn't
  48  * fast enough.  This one _should_ be cryptographically strong, but
  49  * has seen less auditing than the PRNGs in OpenSSL and NSS.  Use with
  50  * caution.
  51  *
  52  * Note that this object is NOT thread-safe.  If you need a thread-safe
  53  * prng, use crypto_rand(), or wrap this in a mutex.
  54  **/
  55 typedef struct crypto_fast_rng_t crypto_fast_rng_t;
  56 /**
  57  * Number of bytes used to seed a crypto_rand_fast_t.
  58  **/
  59 crypto_fast_rng_t *crypto_fast_rng_new(void);
  60 #define CRYPTO_FAST_RNG_SEED_LEN 48
  61 crypto_fast_rng_t *crypto_fast_rng_new_from_seed(const uint8_t *seed);
  62 void crypto_fast_rng_getbytes(crypto_fast_rng_t *rng, uint8_t *out, size_t n);
  63 void crypto_fast_rng_free_(crypto_fast_rng_t *);
  64 #define crypto_fast_rng_free(c)                                 \
  65   FREE_AND_NULL(crypto_fast_rng_t, crypto_fast_rng_free_, (c))
  66
  67 unsigned crypto_fast_rng_get_uint(crypto_fast_rng_t *rng, unsigned limit);
  68 uint64_t crypto_fast_rng_get_uint64(crypto_fast_rng_t *rng, uint64_t limit);
  69 uint32_t crypto_fast_rng_get_u32(crypto_fast_rng_t *rng);
  70 uint64_t crypto_fast_rng_uint64_range(crypto_fast_rng_t *rng,
  71                                       uint64_t min, uint64_t max);
  72 double crypto_fast_rng_get_double(crypto_fast_rng_t *rng);
  73
  74 /**
  75  * Using the fast_rng <b>rng</b>, yield true with probability
  76  * 1/<b>n</b>. Otherwise yield false.
  77  *
  78  * <b>n</b> must not be zero.
  79  **/
  80 #define crypto_fast_rng_one_in_n(rng, n)        \
  81   (0 == (crypto_fast_rng_get_uint((rng), (n))))
  82
  83 crypto_fast_rng_t *get_thread_fast_rng(void);
  84
  85 #ifdef CRYPTO_PRIVATE
  86 /* These are only used from crypto_init.c */
  87 void destroy_thread_fast_rng(void);
  88 void crypto_rand_fast_init(void);
  89 void crypto_rand_fast_shutdown(void);
  90 #endif /* defined(CRYPTO_PRIVATE) */
  91
  92 #if defined(TOR_UNIT_TESTS)
  93 /* Used for white-box testing */
  94 size_t crypto_fast_rng_get_bytes_used_per_stream(void);
  95 /* For deterministic prng implementations */
  96 void crypto_fast_rng_disable_reseed(crypto_fast_rng_t *rng);
  97 /* To override the prng for testing. */
  98 crypto_fast_rng_t *crypto_replace_thread_fast_rng(crypto_fast_rng_t *rng);
  99 #endif /* defined(TOR_UNIT_TESTS) */
 100
 101 #ifdef CRYPTO_RAND_PRIVATE
 102
 103 STATIC int crypto_strongest_rand_raw(uint8_t *out, size_t out_len);
 104
 105 #ifdef TOR_UNIT_TESTS
 106 extern int break_strongest_rng_syscall;
 107 extern int break_strongest_rng_fallback;
 108 #endif
 109 #endif /* defined(CRYPTO_RAND_PRIVATE) */
 110
 111 #endif /* !defined(TOR_CRYPTO_RAND_H) */