golden hour

/usr/include/bind9/isc

File/Folder	Size	Actions
aes.h	1.05 KB
app.h	10.23 KB
assertions.h	2.78 KB
atomic.h	4.15 KB
backtrace.h	3.8 KB
base32.h	3.94 KB
base64.h	2.39 KB
bind9.h	849 B
boolean.h	746 B
buffer.h	25.69 KB
bufferlist.h	1.42 KB
commandline.h	1.69 KB
condition.h	1.44 KB
counter.h	1.88 KB
crc64.h	986 B
deprecated.h	622 B
dir.h	1.96 KB
entropy.h	8.76 KB
errno.h	658 B
errno2result.h	893 B
error.h	1.4 KB
event.h	2.98 KB
eventclass.h	1.35 KB
file.h	11.43 KB
formatcheck.h	892 B
fsaccess.h	7.25 KB
hash.h	7.52 KB
heap.h	5.14 KB
hex.h	2.33 KB
hmacmd5.h	1.75 KB
hmacsha.h	4.44 KB
ht.h	4.29 KB
httpd.h	2.26 KB
int.h	1.37 KB
interfaceiter.h	3.03 KB
iterated_hash.h	1.02 KB
json.h	1.42 KB
keyboard.h	976 B
lang.h	636 B
lex.h	9.42 KB
lfsr.h	2.88 KB
lib.h	1.04 KB
likely.h	718 B
list.h	5.65 KB
log.h	28.06 KB
magic.h	993 B
md5.h	2.34 KB
mem.h	20.63 KB
meminfo.h	690 B
msgcat.h	2.66 KB
msgs.h	8.22 KB
mutex.h	3.44 KB
mutexblock.h	1.34 KB
net.h	10.32 KB
netaddr.h	4.56 KB
netdb.h	862 B
netscope.h	947 B
offset.h	699 B
once.h	981 B
ondestroy.h	2.79 KB
os.h	670 B
parseint.h	1.49 KB
platform.h	9.31 KB
pool.h	3.42 KB
portset.h	3.21 KB
print.h	2.49 KB
queue.h	4.66 KB
quota.h	2.29 KB
radix.h	6.37 KB
random.h	2.99 KB
ratelimiter.h	3.38 KB
refcount.h	7.89 KB
regex.h	766 B
region.h	1.99 KB
resource.h	2.8 KB
result.h	4.62 KB
resultclass.h	1.56 KB
rwlock.h	3.6 KB
safe.h	1.21 KB
serial.h	1.4 KB
sha1.h	1.52 KB
sha2.h	5.65 KB
sockaddr.h	6 KB
socket.h	35.81 KB
stat.h	805 B
stats.h	3.02 KB
stdio.h	1.74 KB
stdlib.h	703 B
stdtime.h	1.3 KB
strerror.h	776 B
string.h	5.94 KB
symtab.h	4.21 KB
syslog.h	843 B
task.h	21.08 KB
taskpool.h	3.61 KB
thread.h	1.47 KB
time.h	8.66 KB
timer.h	10.54 KB
tm.h	894 B
types.h	5.54 KB
util.h	7.49 KB
version.h	688 B
xml.h	1.07 KB

Edit: entropy.h

/*
 * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * See the COPYRIGHT file distributed with this work for additional
 * information regarding copyright ownership.
 */

/* $Id: entropy.h,v 1.35 2009/10/19 02:37:08 marka Exp $ */

#ifndef ISC_ENTROPY_H
#define ISC_ENTROPY_H 1

/*****
 ***** Module Info
 *****/

/*! \file isc/entropy.h
 * \brief The entropy API
 *
 * \li 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.
 *
 * \li Reliability:
 *	No anticipated impact.
 *
 * \li Resources:
 *	A buffer, used as an entropy pool.
 *
 * \li 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.
 *
 * \li Standards:
 *	None.
 */

/***
 *** Imports
 ***/

#include <stdio.h>

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

/*@{*/
/*% Entropy callback function. */
typedef isc_result_t (*isc_entropystart_t)(isc_entropysource_t *source,
					   void *arg, isc_boolean_t blocking);
typedef isc_result_t (*isc_entropyget_t)(isc_entropysource_t *source,
					 void *arg, isc_boolean_t blocking);
typedef void (*isc_entropystop_t)(isc_entropysource_t *source, void *arg);
/*@}*/

/***
 *** Flags.
 ***/

/*!
 * \brief
 *	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_GOODONLY	0x00000001U
/*!
 * \brief
 *	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_PARTIAL	0x00000002U
/*!
 * \brief
 *	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_ENTROPY_BLOCKING	0x00000004U

/*!
 * \brief
 *	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_ENTROPYSOURCE_ESTIMATE	0x00000001U

/*
 * For use with isc_entropy_usebestsource().
 */
/*!
 * \brief
 *	Use the keyboard as the only entropy source.
 */
#define ISC_ENTROPY_KEYBOARDYES		1
/*!
 * \brief
 *	Never use the keyboard as an entropy source.
 */
#define ISC_ENTROPY_KEYBOARDNO		2
/*!
 * \brief
 *	Use the keyboard as an entropy source only if opening the
 *	random device fails.
 */
#define ISC_ENTROPY_KEYBOARDMAYBE	3

ISC_LANG_BEGINDECLS

/***
 *** Functions
 ***/

isc_result_t
isc_entropy_create(isc_mem_t *mctx, isc_entropy_t **entp);
/*!<
 * \brief Create a new entropy object.
 */

void
isc_entropy_attach(isc_entropy_t *ent, isc_entropy_t **entp);
/*!<
 * Attaches to an entropy object.
 */

void
isc_entropy_detach(isc_entropy_t **entp);
/*!<
 * \brief Detaches from an entropy object.
 */

isc_result_t
isc_entropy_createfilesource(isc_entropy_t *ent, const char *fname);
/*!<
 * \brief 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.
 */

void
isc_entropy_destroysource(isc_entropysource_t **sourcep);
/*!<
 * \brief Removes an entropy source from the entropy system.
 */

isc_result_t
isc_entropy_createsamplesource(isc_entropy_t *ent,
			       isc_entropysource_t **sourcep);
/*!<
 * \brief 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);
/*!<
 * \brief 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.
 */

void
isc_entropy_stopcallbacksources(isc_entropy_t *ent);
/*!<
 * \brief Call the stop functions for callback sources that have had their
 * start functions called.
 */

/*@{*/
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);
/*!<
 * \brief 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.
 */
/*@}*/

isc_result_t
isc_entropy_getdata(isc_entropy_t *ent, void *data, unsigned int length,
		    unsigned int *returned, unsigned int flags);
/*!<
 * \brief 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.
 */

void
isc_entropy_putdata(isc_entropy_t *ent, void *data, unsigned int length,
		    isc_uint32_t entropy);
/*!<
 * \brief 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.
 */

void
isc_entropy_stats(isc_entropy_t *ent, FILE *out);
/*!<
 * \brief Dump some (trivial) stats to the stdio stream "out".
 */

unsigned int
isc_entropy_status(isc_entropy_t *end);
/*
 * Returns the number of bits the pool currently contains.  This is just
 * an estimate.
 */

isc_result_t
isc_entropy_usebestsource(isc_entropy_t *ectx, isc_entropysource_t **source,
			  const char *randomfile, int use_keyboard);
/*!<
 * \brief Use whatever source of entropy is best.
 *
 * Notes:
 *\li	If "randomfile" is not NULL, open it with
 *	isc_entropy_createfilesource().
 *
 *\li	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().
 *
 *\li	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).
 *
 *\li	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.
 *
 *\li	If "use_keyboard" is #ISC_ENTROPY_KEYBOARDNO, the keyboard will
 *	never be opened.
 *
 * Returns:
 *\li	#ISC_R_SUCCESS if at least one source of entropy could be started.
 *
 *\li	#ISC_R_NOENTROPY if use_keyboard is #ISC_ENTROPY_KEYBOARDNO and
 *	there is no random device pathname compiled into the program.
 *
 *\li	A return code from isc_entropy_createfilesource() or
 *	isc_entropy_createcallbacksource().
 */

ISC_LANG_ENDDECLS

#endif /* ISC_ENTROPY_H */