crypto_rand.h (4025B)
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) */