entropy.h File Reference

The entropy API. More...

#include <stdio.h>
#include <isc/lang.h>
#include <isc/types.h>

Go to the source code of this file.

Defines
#define	ISC_ENTROPY_H   1
#define	ISC_ENTROPY_GOODONLY   0x00000001U
	Extract only "good" data; return failure if there is not enough data available and there are no sources which we can poll to get data, or those sources are empty.
#define	ISC_ENTROPY_PARTIAL   0x00000002U
	Extract as much good data as possible, but if there isn't enough at hand, return what is available. This flag only makes sense when used with _GOODONLY.
#define	ISC_ENTROPY_BLOCKING   0x00000004U
	Block the task until data is available. This is contrary to the ISC task system, where tasks should never block. However, if this is a special purpose application where blocking a task is acceptable (say, an offline zone signer) this flag may be set. This flag only makes sense when used with _GOODONLY, and will block regardless of the setting for _PARTIAL.
#define	ISC_ENTROPYSOURCE_ESTIMATE   0x00000001U
	Estimate the amount of entropy contained in the sample pool. If this is not set, the source will be gathered and periodically mixed into the entropy pool, but no increment in contained entropy will be assumed. This flag only makes sense on sample sources.
#define	ISC_ENTROPY_KEYBOARDYES   1
	Use the keyboard as the only entropy source.
#define	ISC_ENTROPY_KEYBOARDNO   2
	Never use the keyboard as an entropy source.
#define	ISC_ENTROPY_KEYBOARDMAYBE   3
	Use the keyboard as an entropy source only if opening the random device fails.
Typedefs
typedef isc_result_t(*	isc_entropystart_t )(isc_entropysource_t *source, void *arg, isc_boolean_t blocking)
	Entropy callback function.
typedef isc_result_t(*	isc_entropyget_t )(isc_entropysource_t *source, void *arg, isc_boolean_t blocking)
	Entropy callback function.
typedef void(*	isc_entropystop_t )(isc_entropysource_t *source, void *arg)
	Entropy callback function.
Functions
ISC_LANG_BEGINDECLS isc_result_t	isc_entropy_create (isc_mem_t *mctx, isc_entropy_t **entp)
	Create a new entropy object.
void	isc_entropy_attach (isc_entropy_t *ent, isc_entropy_t **entp)
void	isc_entropy_detach (isc_entropy_t **entp)
	Detaches from an entropy object.
isc_result_t	isc_entropy_createfilesource (isc_entropy_t *ent, const char *fname)
	Create a new entropy source from a file.
void	isc_entropy_destroysource (isc_entropysource_t **sourcep)
	Removes an entropy source from the entropy system.
isc_result_t	isc_entropy_createsamplesource (isc_entropy_t *ent, isc_entropysource_t **sourcep)
	Create an entropy source that consists of samples. Each sample is added to the source via isc_entropy_addsamples(), below.
isc_result_t	isc_entropy_createcallbacksource (isc_entropy_t *ent, isc_entropystart_t start, isc_entropyget_t get, isc_entropystop_t stop, void *arg, isc_entropysource_t **sourcep)
	Create an entropy source that is polled via a callback.
void	isc_entropy_stopcallbacksources (isc_entropy_t *ent)
	Call the stop functions for callback sources that have had their start functions called.
isc_result_t	isc_entropy_getdata (isc_entropy_t *ent, void *data, unsigned int length, unsigned int *returned, unsigned int flags)
	Extract data from the entropy pool. This may load the pool from various sources.
void	isc_entropy_putdata (isc_entropy_t *ent, void *data, unsigned int length, isc_uint32_t entropy)
	Add "length" bytes in "data" to the entropy pool, incrementing the pool's entropy count by "entropy.".
void	isc_entropy_stats (isc_entropy_t *ent, FILE *out)
	Dump some (trivial) stats to the stdio stream "out".
unsigned int	isc_entropy_status (isc_entropy_t *end)
isc_result_t	isc_entropy_usebestsource (isc_entropy_t *ectx, isc_entropysource_t **source, const char *randomfile, int use_keyboard)
	Use whatever source of entropy is best.
isc_result_t	isc_entropy_addcallbacksample (isc_entropysource_t *source, isc_uint32_t sample, isc_uint32_t extra)
isc_result_t	isc_entropy_addsample (isc_entropysource_t *source, isc_uint32_t sample, isc_uint32_t extra)
	Add a sample to the sample source.

---

Detailed Description

The entropy API.

• MP: The entropy object is locked internally. All callbacks into application-provided functions (for setup, gathering, and shutdown of sources) are guaranteed to be called with the entropy API lock held. This means these functions are not permitted to call back into the entropy API.

• Reliability: No anticipated impact.

• Resources: A buffer, used as an entropy pool.

• Security: While this code is believed to implement good entropy gathering and distribution, it has not been reviewed by a cryptographic expert. Since the added entropy is only as good as the sources used, this module could hand out bad data and never know it.

• Standards: None.

Definition in file entropy.h.

---

Define Documentation

#define ISC_ENTROPY_H   1

Definition at line 21 of file entropy.h.

#define ISC_ENTROPY_GOODONLY   0x00000001U

Extract only "good" data; return failure if there is not enough data available and there are no sources which we can poll to get data, or those sources are empty.

Definition at line 84 of file entropy.h.

Referenced by dst__entropy_getdata(), dst__entropy_status(), isc_entropy_getdata(), main(), and ns_server_create().

#define ISC_ENTROPY_PARTIAL   0x00000002U

Extract as much good data as possible, but if there isn't enough at hand, return what is available. This flag only makes sense when used with _GOODONLY.

Definition at line 91 of file entropy.h.

Referenced by isc_entropy_getdata().

#define ISC_ENTROPY_BLOCKING   0x00000004U

Block the task until data is available. This is contrary to the ISC task system, where tasks should never block. However, if this is a special purpose application where blocking a task is acceptable (say, an offline zone signer) this flag may be set. This flag only makes sense when used with _GOODONLY, and will block regardless of the setting for _PARTIAL.

Definition at line 101 of file entropy.h.

Referenced by dns_test_begin(), dst__entropy_getdata(), isc_entropy_getdata(), and main().

#define ISC_ENTROPYSOURCE_ESTIMATE   0x00000001U

Estimate the amount of entropy contained in the sample pool. If this is not set, the source will be gathered and periodically mixed into the entropy pool, but no increment in contained entropy will be assumed. This flag only makes sense on sample sources.

Definition at line 110 of file entropy.h.

#define ISC_ENTROPY_KEYBOARDYES   1

Use the keyboard as the only entropy source.

Definition at line 119 of file entropy.h.

Referenced by isc_entropy_usebestsource(), ISC_LIST(), and setup_entropy().

#define ISC_ENTROPY_KEYBOARDNO   2

Never use the keyboard as an entropy source.

Definition at line 124 of file entropy.h.

Referenced by isc_entropy_usebestsource().

#define ISC_ENTROPY_KEYBOARDMAYBE   3

Use the keyboard as an entropy source only if opening the random device fails.

Definition at line 130 of file entropy.h.

Referenced by isc_entropy_usebestsource(), ISC_LIST(), and setup_entropy().

---

Typedef Documentation

typedef isc_result_t(* isc_entropystart_t)(isc_entropysource_t *source, void *arg, isc_boolean_t blocking)

Entropy callback function.

Definition at line 65 of file entropy.h.

typedef isc_result_t(* isc_entropyget_t)(isc_entropysource_t *source, void *arg, isc_boolean_t blocking)

Entropy callback function.

Definition at line 67 of file entropy.h.

typedef void(* isc_entropystop_t)(isc_entropysource_t *source, void *arg)

Entropy callback function.

Definition at line 69 of file entropy.h.

---

Function Documentation

ISC_LANG_BEGINDECLS isc_result_t isc_entropy_create	(	isc_mem_t *	mctx,
		isc_entropy_t **	entp
	)

Create a new entropy object.

Definition at line 682 of file entropy.c.

References ENTROPY_MAGIC, isc_entropy::initcount, isc_entropy::initialized, isc_entropypool_init(), ISC_LIST_INIT, isc_mem_attach(), isc_mem_get, isc_mem_put, isc_mutex_init, ISC_R_NOMEMORY, ISC_R_SUCCESS, isc_entropy::lock, isc_entropy::magic, isc_entropy::mctx, isc_entropy::nextsource, isc_entropy::nsources, isc_entropy::pool, isc_entropy::refcnt, and REQUIRE.

Referenced by create_managers(), dns_test_begin(), ISC_LIST(), isc_test_begin(), main(), setup(), setup_entropy(), and setup_libs().

void isc_entropy_attach	(	isc_entropy_t *	ent,
		isc_entropy_t **	entp
	)

Attaches to an entropy object.

Definition at line 1128 of file entropy.c.

References isc_entropy::lock, LOCK, isc_entropy::refcnt, REQUIRE, UNLOCK, and VALID_ENTROPY.

Referenced by dns_dispatchmgr_create(), dns_tkeyctx_create(), dst_lib_init2(), isc_hash_ctxcreate(), and load_configuration().

void isc_entropy_detach

(

isc_entropy_t **

entp

)

Detaches from an entropy object.

Definition at line 1141 of file entropy.c.

References destroy(), destroy_check(), isc_entropy::lock, LOCK, isc_entropy::refcnt, REQUIRE, UNLOCK, and VALID_ENTROPY.

Referenced by cleanup(), cleanup_entropy(), destroy(), destroy_libs(), destroy_mgr(), dns_test_end(), dns_tkeyctx_destroy(), dst_lib_destroy(), isc_test_end(), load_configuration(), main(), and setup().

isc_result_t isc_entropy_createfilesource	(	isc_entropy_t *	ent,
		const char *	fname
	)

Create a new entropy source from a file.

The file is assumed to contain good randomness, and will be mixed directly into the pool with every byte adding 8 bits of entropy.

The file will be put into non-blocking mode, so it may be a device file, such as /dev/random. /dev/urandom should not be used here if it can be avoided, since it will always provide data even if it isn't good. We will make as much pseudorandom data as we need internally if our caller asks for it.

If we hit end-of-file, we will stop reading from this source. Callers who require strong random data will get failure when our pool drains. The file will never be opened/read again once EOF is reached.

Definition at line 488 of file entropy.c.

References isc_entropysource::ent, ENTROPY_SOURCETYPE_FILE, ENTROPY_SOURCETYPE_USOCKET, isc__errno2result, ISC_FALSE, ISC_LINK_INIT, ISC_LIST_APPEND, isc_mem_get, ISC_R_NOMEMORY, ISC_R_SUCCESS, ISC_TRUE, isc_entropy::lock, LOCK, isc_entropysource::magic, make_nonblock(), isc_entropy::mctx, isc_entropy::nsources, REQUIRE, SOURCE_MAGIC, isc_entropysource::sources, isc_entropysource::total, isc_entropysource::type, UNLOCK, and VALID_ENTROPY.

Referenced by isc_entropy_usebestsource(), load_configuration(), and setup().

void isc_entropy_destroysource

(

isc_entropysource_t **

sourcep

)

Removes an entropy source from the entropy system.

Definition at line 838 of file entropy.c.

References destroy(), destroy_check(), destroysource(), isc_entropysource::ent, isc_entropy::lock, LOCK, REQUIRE, UNLOCK, VALID_ENTROPY, and VALID_SOURCE.

Referenced by cleanup_entropy().

isc_result_t isc_entropy_createsamplesource	(	isc_entropy_t *	ent,
		isc_entropysource_t **	sourcep
	)

Create an entropy source that consists of samples. Each sample is added to the source via isc_entropy_addsamples(), below.

Definition at line 957 of file entropy.c.

References isc_entropysource::ent, ENTROPY_SOURCETYPE_SAMPLE, ISC_LINK_INIT, ISC_LIST_APPEND, isc_mem_get, isc_mem_put, ISC_R_NOMEMORY, ISC_R_SUCCESS, isc_entropy::lock, LOCK, isc_entropysource::magic, isc_entropy::mctx, isc_entropy::nsources, REQUIRE, samplesource_allocate(), SOURCE_MAGIC, isc_entropysource::sources, isc_entropysource::total, isc_entropysource::type, UNLOCK, and VALID_ENTROPY.

isc_result_t isc_entropy_createcallbacksource	(	isc_entropy_t *	ent,
		isc_entropystart_t	start,
		isc_entropyget_t	get,
		isc_entropystop_t	stop,
		void *	arg,
		isc_entropysource_t **	sourcep
	)

Create an entropy source that is polled via a callback.

This would be used when keyboard input is used, or a GUI input method. It can also be used to hook in any external entropy source.

Samples are added via isc_entropy_addcallbacksample(), below. _addcallbacksample() is the only function which may be called from within an entropy API callback function.

Definition at line 865 of file entropy.c.

References isc_cbsource_t::arg, isc_entropysource::ent, ENTROPY_SOURCETYPE_CALLBACK, isc_cbsource_t::getfunc, ISC_FALSE, ISC_LINK_INIT, ISC_LIST_APPEND, isc_mem_get, isc_mem_put, ISC_R_NOMEMORY, ISC_R_SUCCESS, isc_entropy::lock, LOCK, isc_entropysource::magic, isc_entropy::mctx, isc_entropy::nsources, REQUIRE, isc_cbsource_t::samplequeue, samplesource_allocate(), SOURCE_MAGIC, isc_entropysource::sources, isc_cbsource_t::start_called, isc_cbsource_t::startfunc, isc_cbsource_t::stopfunc, isc_entropysource::total, isc_entropysource::type, UNLOCK, and VALID_ENTROPY.

Referenced by isc_entropy_usebestsource().

void isc_entropy_stopcallbacksources

(

isc_entropy_t *

ent

)

Call the stop functions for callback sources that have had their start functions called.

Definition at line 932 of file entropy.c.

References isc_cbsource_t::arg, ENTROPY_SOURCETYPE_CALLBACK, ISC_FALSE, ISC_LIST_HEAD, ISC_LIST_NEXT, isc_entropy::lock, LOCK, REQUIRE, isc_entropysource::sources, isc_cbsource_t::start_called, isc_cbsource_t::stopfunc, isc_entropysource::type, UNLOCK, and VALID_ENTROPY.

Referenced by main(), and signwithkey().

isc_result_t isc_entropy_addcallbacksample	(	isc_entropysource_t *	source,
		isc_uint32_t	sample,
		isc_uint32_t	extra
	)

Definition at line 1058 of file entropy.c.

References addsample(), ENTROPY_SOURCETYPE_CALLBACK, REQUIRE, isc_entropysource::sources, isc_entropysource::type, and VALID_SOURCE.

Referenced by kbdget().

isc_result_t isc_entropy_addsample	(	isc_entropysource_t *	source,
		isc_uint32_t	sample,
		isc_uint32_t	extra
	)

Add a sample to the sample source.

The sample MUST be a timestamp that increases over time, with the exception of wrap-around for extremely high resolution timers which will quickly wrap-around a 32-bit integer.

The "extra" parameter is used only to add a bit more unpredictable data. It is not used other than included in the hash of samples.

When in an entropy API callback function, _addcallbacksource() must be used. At all other times, _addsample() must be used.

Definition at line 1031 of file entropy.c.

References add_entropy(), addsample(), crunchsamples(), isc_entropysource::ent, entropy, ISC_R_QUEUEFULL, isc_entropy::lock, LOCK, REQUIRE, isc_entropysource::sources, UNLOCK, and VALID_SOURCE.

isc_result_t isc_entropy_getdata	(	isc_entropy_t *	ent,
		void *	data,
		unsigned int	length,
		unsigned int *	returned,
		unsigned int	flags
	)

Extract data from the entropy pool. This may load the pool from various sources.

Do this by stiring the pool and returning a part of hash as randomness. Note that no secrets are given away here since parts of the hash are xored together before returned.

Honor the request from the caller to only return good data, any data, etc.

Definition at line 538 of file entropy.c.

References add_entropy(), add_pseudo(), digest, isc_entropypool_t::entropy, entropypool_adddata(), fillpool(), hash, isc_entropy::initialized, ISC_ENTROPY_BLOCKING, ISC_ENTROPY_GOODONLY, ISC_ENTROPY_PARTIAL, ISC_FALSE, ISC_MAX, ISC_MIN, ISC_R_NOENTROPY, ISC_R_SUCCESS, ISC_SHA1_DIGESTLENGTH, isc_sha1_final(), isc_sha1_init(), isc_sha1_update(), ISC_TF, isc_entropy::lock, LOCK, isc_entropypool_t::pool, isc_entropy::pool, REQUIRE, reseed(), RND_ENTROPY_THRESHOLD, RND_POOLBYTES, subtract_entropy(), THRESHOLD_BITS, UNLOCK, and VALID_ENTROPY.

Referenced by chacha_stir(), create_view(), dns_tkey_processquery(), dst__entropy_getdata(), dst__entropy_status(), isc_hash_ctxinit(), isc_rng_create(), load_configuration(), and setup_system().

void isc_entropy_putdata	(	isc_entropy_t *	ent,
		void *	data,
		unsigned int	length,
		isc_uint32_t	entropy
	)

Add "length" bytes in "data" to the entropy pool, incrementing the pool's entropy count by "entropy.".

These bytes will prime the pseudorandom portion even if no entropy is actually added.

Definition at line 1074 of file entropy.c.

References entropypool_adddata(), isc_entropy::initialized, isc_entropy::lock, LOCK, REQUIRE, THRESHOLD_BITS, UNLOCK, and VALID_ENTROPY.

Referenced by dst__entropy_status().

void isc_entropy_stats	(	isc_entropy_t *	ent,
		FILE *	out
	)

Dump some (trivial) stats to the stdio stream "out".

Definition at line 1108 of file entropy.c.

References dumpstats(), isc_entropy::lock, LOCK, REQUIRE, UNLOCK, and VALID_ENTROPY.

unsigned int isc_entropy_status

(

isc_entropy_t *

end

)

Definition at line 1117 of file entropy.c.

References isc_entropypool_t::entropy, isc_entropy::lock, LOCK, isc_entropy::pool, and UNLOCK.

Referenced by dst__entropy_status().

isc_result_t isc_entropy_usebestsource	(	isc_entropy_t *	ectx,
		isc_entropysource_t **	source,
		const char *	randomfile,
		int	use_keyboard
	)

Use whatever source of entropy is best.

Notes:

• If "randomfile" is not NULL, open it with isc_entropy_createfilesource().

• If "randomfile" is NULL and the system's random device was detected when the program was configured and built, open that device with isc_entropy_createfilesource().

• If "use_keyboard" is ISC_ENTROPY_KEYBOARDYES, then always open the keyboard as an entropy source (possibly in addition to "randomfile" or the random device).

• If "use_keyboard" is ISC_ENTROPY_KEYBOARDMAYBE, open the keyboard only if opening the random file/device fails. A message will be printed describing the need for keyboard input.

• If "use_keyboard" is ISC_ENTROPY_KEYBOARDNO, the keyboard will never be opened.

Returns:

• ISC_R_SUCCESS if at least one source of entropy could be started.

• ISC_R_NOENTROPY if use_keyboard is ISC_ENTROPY_KEYBOARDNO and there is no random device pathname compiled into the program.

• A return code from isc_entropy_createfilesource() or isc_entropy_createcallbacksource().

Definition at line 1234 of file entropy.c.

References isc_entropy_createcallbacksource(), isc_entropy_createfilesource(), ISC_ENTROPY_KEYBOARDMAYBE, ISC_ENTROPY_KEYBOARDNO, ISC_ENTROPY_KEYBOARDYES, ISC_FALSE, ISC_R_NOENTROPY, ISC_R_SUCCESS, ISC_TF, ISC_TRUE, kbdget(), kbdstart(), kbdstop(), pk11_rand_seed_fromfile(), REQUIRE, and VALID_ENTROPY.

Referenced by ISC_LIST(), and setup_entropy().

---