Tor 0.4.9.0-alpha-dev
crypto_rand.h
Go to the documentation of this file.
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
17#include "lib/cc/torint.h"
19#include "lib/malloc/malloc.h"
20
21/* random numbers */
22int crypto_seed_rng(void) ATTR_WUR;
23MOCK_DECL(void,crypto_rand,(char *to, size_t n));
24void crypto_rand_unmocked(char *to, size_t n);
25void crypto_strongest_rand(uint8_t *out, size_t out_len);
26MOCK_DECL(void,crypto_strongest_rand_,(uint8_t *out, size_t out_len));
27int crypto_rand_int(unsigned int max);
28unsigned crypto_rand_uint(unsigned limit);
29int crypto_rand_int_range(unsigned int min, unsigned int max);
30uint64_t crypto_rand_uint64_range(uint64_t min, uint64_t max);
31time_t crypto_rand_time_range(time_t min, time_t max);
32uint32_t crypto_rand_u32(void);
33uint64_t crypto_rand_uint64(uint64_t max);
34double crypto_rand_double(void);
35struct tor_weak_rng_t;
36void crypto_seed_weak_rng(struct tor_weak_rng_t *rng);
37
38char *crypto_random_hostname(int min_rand_len, int max_rand_len,
39 const char *prefix, const char *suffix);
40
41struct smartlist_t;
42void *smartlist_choose(const struct smartlist_t *sl);
43void smartlist_shuffle(struct smartlist_t *sl);
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 **/
56/**
57 * Number of bytes used to seed a crypto_rand_fast_t.
58 **/
60#define CRYPTO_FAST_RNG_SEED_LEN 48
62void crypto_fast_rng_getbytes(crypto_fast_rng_t *rng, uint8_t *out, size_t n);
64#define crypto_fast_rng_free(c) \
65 FREE_AND_NULL(crypto_fast_rng_t, crypto_fast_rng_free_, (c))
66
67unsigned crypto_fast_rng_get_uint(crypto_fast_rng_t *rng, unsigned limit);
68uint64_t crypto_fast_rng_get_uint64(crypto_fast_rng_t *rng, uint64_t limit);
71 uint64_t min, uint64_t max);
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
84
85#ifdef CRYPTO_PRIVATE
86/* These are only used from crypto_init.c */
88void crypto_rand_fast_init(void);
90#endif /* defined(CRYPTO_PRIVATE) */
91
92#if defined(TOR_UNIT_TESTS)
93/* Used for white-box testing */
94size_t crypto_fast_rng_get_bytes_used_per_stream(void);
95/* For deterministic prng implementations */
96void crypto_fast_rng_disable_reseed(crypto_fast_rng_t *rng);
97/* To override the prng for testing. */
98crypto_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
103STATIC int crypto_strongest_rand_raw(uint8_t *out, size_t out_len);
104
105#ifdef TOR_UNIT_TESTS
106extern int break_strongest_rng_syscall;
107extern int break_strongest_rng_fallback;
108#endif
109#endif /* defined(CRYPTO_RAND_PRIVATE) */
110
111#endif /* !defined(TOR_CRYPTO_RAND_H) */
Utility macros to handle different features and behavior in different compilers.
void * smartlist_choose(const smartlist_t *sl)
Definition: crypto_rand.c:594
STATIC int crypto_strongest_rand_raw(uint8_t *out, size_t out_len)
Definition: crypto_rand.c:291
uint64_t crypto_fast_rng_uint64_range(crypto_fast_rng_t *rng, uint64_t min, uint64_t max)
crypto_fast_rng_t * get_thread_fast_rng(void)
int crypto_seed_rng(void) ATTR_WUR
Definition: crypto_rand.c:454
char * crypto_random_hostname(int min_rand_len, int max_rand_len, const char *prefix, const char *suffix)
Definition: crypto_rand.c:554
crypto_fast_rng_t * crypto_fast_rng_new_from_seed(const uint8_t *seed)
void smartlist_shuffle(struct smartlist_t *sl)
Definition: crypto_rand.c:606
time_t crypto_rand_time_range(time_t min, time_t max)
void crypto_strongest_rand_(uint8_t *out, size_t out_len)
Definition: crypto_rand.c:352
void crypto_rand(char *to, size_t n)
Definition: crypto_rand.c:479
uint64_t crypto_rand_uint64_range(uint64_t min, uint64_t max)
double crypto_fast_rng_get_double(crypto_fast_rng_t *rng)
uint32_t crypto_fast_rng_get_u32(crypto_fast_rng_t *rng)
uint64_t crypto_fast_rng_get_uint64(crypto_fast_rng_t *rng, uint64_t limit)
uint32_t crypto_rand_u32(void)
Definition: crypto_rand.c:538
unsigned crypto_fast_rng_get_uint(crypto_fast_rng_t *rng, unsigned limit)
unsigned crypto_rand_uint(unsigned limit)
void crypto_rand_unmocked(char *to, size_t n)
Definition: crypto_rand.c:492
void crypto_seed_weak_rng(struct tor_weak_rng_t *rng)
Definition: crypto_rand.c:112
void crypto_fast_rng_free_(crypto_fast_rng_t *)
int crypto_force_rand_ssleay(void)
Definition: crypto_rand.c:622
double crypto_rand_double(void)
int crypto_rand_int_range(unsigned int min, unsigned int max)
void crypto_fast_rng_getbytes(crypto_fast_rng_t *rng, uint8_t *out, size_t n)
uint64_t crypto_rand_uint64(uint64_t max)
crypto_fast_rng_t * crypto_fast_rng_new(void)
void crypto_strongest_rand(uint8_t *out, size_t out_len)
Definition: crypto_rand.c:342
int crypto_rand_int(unsigned int max)
void destroy_thread_fast_rng(void)
void crypto_rand_fast_init(void)
void crypto_rand_fast_shutdown(void)
Headers for util_malloc.c.
Macros to implement mocking and selective exposure for the test code.
#define STATIC
Definition: testsupport.h:32
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127
Integer definitions used throughout Tor.