crypto_rand.h File Reference

Common functions for using (pseudo-)random number generators. More...

#include "lib/cc/compat_compiler.h"
#include "lib/cc/torint.h"
#include "lib/testsupport/testsupport.h"
#include "lib/malloc/malloc.h"

Go to the source code of this file.

Macros
#define	CRYPTO_FAST_RNG_SEED_LEN   48
#define	crypto_fast_rng_free(c)    FREE_AND_NULL(crypto_fast_rng_t, crypto_fast_rng_free_, (c))
#define	crypto_fast_rng_one_in_n(rng, n)    (0 == (crypto_fast_rng_get_uint((rng), (n))))

Functions
int	crypto_seed_rng (void) ATTR_WUR
void	crypto_rand (char *to, size_t n)
void	crypto_rand_unmocked (char *to, size_t n)
void	crypto_strongest_rand (uint8_t *out, size_t out_len)
void	crypto_strongest_rand_ (uint8_t *out, size_t out_len)
int	crypto_rand_int (unsigned int max)
unsigned	crypto_rand_uint (unsigned limit)
int	crypto_rand_int_range (unsigned int min, unsigned int max)
uint64_t	crypto_rand_uint64_range (uint64_t min, uint64_t max)
time_t	crypto_rand_time_range (time_t min, time_t max)
uint32_t	crypto_rand_u32 (void)
uint64_t	crypto_rand_uint64 (uint64_t max)
double	crypto_rand_double (void)
void	crypto_seed_weak_rng (struct tor_weak_rng_t *rng)
char *	crypto_random_hostname (int min_rand_len, int max_rand_len, const char *prefix, const char *suffix)
void *	smartlist_choose (const struct smartlist_t *sl)
void	smartlist_shuffle (struct smartlist_t *sl)
int	crypto_force_rand_ssleay (void)
crypto_fast_rng_t *	crypto_fast_rng_new (void)
crypto_fast_rng_t *	crypto_fast_rng_new_from_seed (const uint8_t *seed)
void	crypto_fast_rng_getbytes (crypto_fast_rng_t *rng, uint8_t *out, size_t n)
void	crypto_fast_rng_free_ (crypto_fast_rng_t *)
unsigned	crypto_fast_rng_get_uint (crypto_fast_rng_t *rng, unsigned limit)
uint64_t	crypto_fast_rng_get_uint64 (crypto_fast_rng_t *rng, uint64_t limit)
uint32_t	crypto_fast_rng_get_u32 (crypto_fast_rng_t *rng)
uint64_t	crypto_fast_rng_uint64_range (crypto_fast_rng_t *rng, uint64_t min, uint64_t max)
double	crypto_fast_rng_get_double (crypto_fast_rng_t *rng)
crypto_fast_rng_t *	get_thread_fast_rng (void)

Detailed Description

Common functions for using (pseudo-)random number generators.

Definition in file crypto_rand.h.

Macro Definition Documentation

crypto_fast_rng_one_in_n

#define crypto_fast_rng_one_in_n	(		rng,
			n
	)		(0 == (crypto_fast_rng_get_uint((rng), (n))))

Using the fast_rng rng, yield true with probability 1/n. Otherwise yield false.

n must not be zero.

Definition at line 80 of file crypto_rand.h.

Function Documentation

crypto_fast_rng_free_()

void crypto_fast_rng_free_

(

crypto_fast_rng_t *

rng

)

Release all storage held by rng.

Definition at line 273 of file crypto_rand_fast.c.

crypto_fast_rng_get_double()

double crypto_fast_rng_get_double

(

crypto_fast_rng_t *

rng

)

As crypto_rand_get_double() but extract the result from a crypto_fast_rng_t.

Definition at line 188 of file crypto_rand_numeric.c.

crypto_fast_rng_get_u32()

uint32_t crypto_fast_rng_get_u32

(

crypto_fast_rng_t *

rng

)

As crypto_rand_u32, but extract the result from a crypto_fast_rng_t.

Definition at line 161 of file crypto_rand_numeric.c.

Referenced by genpareto_sample(), geometric_sample(), log_logistic_sample(), logistic_sample(), random_uniform_01(), and weibull_sample().

crypto_fast_rng_get_uint()

unsigned crypto_fast_rng_get_uint	(	crypto_fast_rng_t *	rng,
		unsigned	limit
	)

As crypto_rand_uint, but extract the result from a crypto_fast_rng_t

Definition at line 139 of file crypto_rand_numeric.c.

Referenced by circuit_reset_sendme_randomness(), and extend_info_pick_orport().

crypto_fast_rng_get_uint64()

uint64_t crypto_fast_rng_get_uint64	(	crypto_fast_rng_t *	rng,
		uint64_t	limit
	)

As crypto_rand_uint64, but extract the result from a crypto_fast_rng_t.

Definition at line 150 of file crypto_rand_numeric.c.

crypto_fast_rng_getbytes()

void crypto_fast_rng_getbytes	(	crypto_fast_rng_t *	rng,
		uint8_t *	out,
		size_t	n
	)

Extract n bytes from rng into the buffer at out.

Definition at line 334 of file crypto_rand_fast.c.

Referenced by crypto_fast_rng_get_double(), crypto_fast_rng_get_u32(), crypto_fast_rng_get_uint(), and crypto_fast_rng_get_uint64().

crypto_fast_rng_new()

crypto_fast_rng_t* crypto_fast_rng_new

(

void

)

Number of bytes used to seed a crypto_rand_fast_t.

Initialize and return a new fast PRNG, using a strong random seed.

Note that this object is NOT thread-safe. If you need a thread-safe prng, use crypto_rand(), or wrap this in a mutex.

Definition at line 138 of file crypto_rand_fast.c.

crypto_fast_rng_new_from_seed()

crypto_fast_rng_t* crypto_fast_rng_new_from_seed

(

const uint8_t *

seed

)

Initialize and return a new fast PRNG, using a seed value specified in seed. This value must be CRYPTO_FAST_RNG_SEED_LEN bytes long.

Note that this object is NOT thread-safe. If you need a thread-safe prng, you should probably look at get_thread_fast_rng(). Alternatively, use crypto_rand(), wrap this in a mutex.

Definition at line 157 of file crypto_rand_fast.c.

crypto_fast_rng_uint64_range()

uint64_t crypto_fast_rng_uint64_range	(	crypto_fast_rng_t *	rng,
		uint64_t	min,
		uint64_t	max
	)

As crypto_rand_uint64_range(), but extract the result from a crypto_fast_rng_t.

Definition at line 173 of file crypto_rand_numeric.c.

crypto_force_rand_ssleay()

int crypto_force_rand_ssleay

(

void

)

Make sure that openssl is using its default PRNG. Return 1 if we had to adjust it; 0 otherwise.

Definition at line 618 of file crypto_rand.c.

crypto_rand()

void crypto_rand	(	char *	to,
		size_t	n
	)

Write n bytes of strong random data to to. Supports mocking for unit tests.

This function is not allowed to fail; if it would fail to generate strong entropy, it must terminate the process instead.

Definition at line 477 of file crypto_rand.c.

Referenced by connection_or_send_auth_challenge_cell(), crypto_cipher_encrypt_with_iv(), crypto_pk_obsolete_public_hybrid_encrypt(), crypto_rand_double(), crypto_rand_u32(), crypto_rand_uint(), crypto_rand_uint64(), crypto_seed_weak_rng(), curve25519_rand_seckey_bytes(), do_hash_password(), ed25519_secret_key_generate(), fast_server_handshake(), and get_random_virtual_addr().

crypto_rand_double()

double crypto_rand_double

(

void

)

Return a pseudorandom double d, chosen uniformly from the range 0.0 <= d < 1.0.

Definition at line 126 of file crypto_rand_numeric.c.

crypto_rand_int()

int crypto_rand_int

(

unsigned int

max

)

Return a pseudorandom integer, chosen uniformly from the values between 0 and max-1 inclusive. max must be between 1 and INT_MAX+1, inclusive.

Definition at line 52 of file crypto_rand_numeric.c.

Referenced by channelpadding_get_circuits_available_timeout(), channelpadding_get_netflow_inactive_timeout_ms(), choose_array_element_by_weight(), and crypto_rand_int_range().

crypto_rand_int_range()

int crypto_rand_int_range	(	unsigned int	min,
		unsigned int	max
	)

Return a pseudorandom integer, chosen uniformly from the values i such that min <= i < max.

min MUST be in range [0, max). max MUST be in range (min, INT_MAX].

Definition at line 71 of file crypto_rand_numeric.c.

Referenced by crypto_random_hostname().

crypto_rand_time_range()

time_t crypto_rand_time_range	(	time_t	min,
		time_t	max
	)

As crypto_rand_int_range, but supports time_t.

Definition at line 95 of file crypto_rand_numeric.c.

Referenced by randomize_time().

crypto_rand_u32()

uint32_t crypto_rand_u32

(

void

)

Draw an unsigned 32-bit integer uniformly at random.

Definition at line 536 of file crypto_rand.c.

crypto_rand_uint()

unsigned crypto_rand_uint

(

unsigned

limit

)

Return a pseudorandom integer chosen uniformly from the values between 0 and limit-1 inclusive. limit must be strictly greater than 0, and less than UINT_MAX.

Definition at line 39 of file crypto_rand_numeric.c.

Referenced by crypto_rand_int().

crypto_rand_uint64()

uint64_t crypto_rand_uint64

(

uint64_t

max

)

Return a pseudorandom 64-bit integer, chosen uniformly from the values between 0 and max-1 inclusive.

Definition at line 106 of file crypto_rand_numeric.c.

Referenced by choose_array_element_by_weight(), crypto_rand_time_range(), and crypto_rand_uint64_range().

crypto_rand_uint64_range()

uint64_t crypto_rand_uint64_range	(	uint64_t	min,
		uint64_t	max
	)

As crypto_rand_int_range, but supports uint64_t.

Definition at line 85 of file crypto_rand_numeric.c.

crypto_rand_unmocked()

void crypto_rand_unmocked	(	char *	to,
		size_t	n
	)

Write n bytes of strong random data to to. Most callers will want crypto_rand instead.

This function is not allowed to fail; if it would fail to generate strong entropy, it must terminate the process instead.

Definition at line 490 of file crypto_rand.c.

Referenced by crypto_rand().

crypto_random_hostname()

char* crypto_random_hostname	(	int	min_rand_len,
		int	max_rand_len,
		const char *	prefix,
		const char *	suffix
	)

Generate and return a new random hostname starting with prefix, ending with suffix, and containing no fewer than min_rand_len and no more than max_rand_len random base32 characters. Does not check for failure.

Clip max_rand_len to MAX_DNS_LABEL_SIZE.

Definition at line 552 of file crypto_rand.c.

Referenced by launch_wildcard_check(), and tor_tls_context_init_certificates().

crypto_seed_rng()

int crypto_seed_rng

(

void

)

Seed the RNG for any and all crypto libraries that we're using with bytes from the operating system. Return 0 on success, -1 on failure.

Definition at line 452 of file crypto_rand.c.

Referenced by add_entropy_callback().

crypto_seed_weak_rng()

void crypto_seed_weak_rng

(

tor_weak_rng_t *

rng

)

Set the seed of the weak RNG to a random value.

Definition at line 110 of file crypto_rand.c.

crypto_strongest_rand()

void crypto_strongest_rand	(	uint8_t *	out,
		size_t	out_len
	)

Try to get out_len bytes of the strongest entropy we can generate, storing it into out.

Definition at line 340 of file crypto_rand.c.

Referenced by curve25519_rand_seckey_bytes(), ed25519_secret_key_generate(), encrypt_descriptor_data(), and sr_generate_our_commit().

crypto_strongest_rand_()

void crypto_strongest_rand_	(	uint8_t *	out,
		size_t	out_len
	)

Try to get out_len bytes of the strongest entropy we can generate, storing it into out. (Mockable version.)

Definition at line 350 of file crypto_rand.c.

Referenced by crypto_strongest_rand().

get_thread_fast_rng()

crypto_fast_rng_t* get_thread_fast_rng

(

void

)

Return a per-thread fast RNG, initializing it if necessary.

You do not need to free this yourself.

It is NOT safe to share this value across threads.

Definition at line 377 of file crypto_rand_fast.c.

Referenced by circuit_reset_sendme_randomness(), circuit_resume_edge_reading_helper(), extend_info_pick_orport(), genpareto_sample(), geometric_sample(), log_logistic_sample(), logistic_sample(), random_uniform_01(), and weibull_sample().

smartlist_shuffle()

void smartlist_shuffle

(

smartlist_t *

sl

)

Scramble the elements of sl into a random order.

Definition at line 602 of file crypto_rand.c.