entropy.h revision 15a44745412679c30a6d022733925af70a38b715
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Copyright (C) 2000 Internet Software Consortium.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Permission to use, copy, modify, and distribute this software for any
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * purpose with or without fee is hereby granted, provided that the above
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * copyright notice and this permission notice appear in all copies.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews/* $Id: entropy.h,v 1.20 2000/07/27 09:51:32 tale Exp $ */
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews ***** Module Info
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * The entropy API
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * The entropy object is locked internally. All callbacks into
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * application-provided functions (for setup, gathering, and
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * shutdown of sources) are guaranteed to be called with the
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * entropy API lock held. This means these functions are
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * not permitted to call back into the entropy API.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Reliability:
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * No anticipated impact.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Resources:
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * A buffer, used as an entropy pool.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * While this code is believed to implement good entropy gathering
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * and distribution, it has not been reviewed by a cryptographic
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Since the added entropy is only as good as the sources used,
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * this module could hand out bad data and never know it.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Standards:
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Entropy callback function.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewstypedef isc_result_t (*isc_entropystart_t)(isc_entropysource_t *source,
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewstypedef isc_result_t (*isc_entropyget_t)(isc_entropysource_t *source,
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewstypedef void (*isc_entropystop_t)(isc_entropysource_t *source, void *arg);
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Extract only "good" data; return failure if there is not enough
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * data available and there are no sources which we can poll to get
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * data, or those sources are empty.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Extract as much good data as possible, but if there isn't enough
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * at hand, return what is available. This flag only makes sense
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * when used with _GOODONLY.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Block the task until data is available. This is contrary to the
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * ISC task system, where tasks should never block. However, if
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * this is a special purpose application where blocking a task is
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * acceptable (say, an offline zone signer) this flag may be set.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * This flag only makes sense when used with _GOODONLY, and will
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * block regardless of the setting for _PARTIAL.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Estimate the amount of entropy contained in the sample pool.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * If this is not set, the source will be gathered and perodically
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * mixed into the entropy pool, but no increment in contained entropy
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * will be assumed. This flag only makes sense on sample sources.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews *** Functions
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewsisc_entropy_create(isc_mem_t *mctx, isc_entropy_t **entp);
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Create a new entropy object.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewsisc_entropy_attach(isc_entropy_t *ent, isc_entropy_t **entp);
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Attaches to an entropy object.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Detaches from an entropy object.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewsisc_entropy_createfilesource(isc_entropy_t *ent, const char *fname);
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Create a new entropy source from a file.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * The file is assumed to contain good randomness, and will be mixed directly
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * into the pool with every byte adding 8 bits of entropy.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * The file will be put into non-blocking mode, so it may be a device file,
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * such as /dev/random. /dev/urandom should not be used here if it can
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * be avoided, since it will always provide data even if it isn't good.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * We will make as much pseudorandom data as we need internally if our
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * caller asks for it.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * If we hit end-of-file, we will stop reading from this source. Callers
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * who require strong random data will get failure when our pool drains.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * The file will never be opened/read again once EOF is reached.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewsisc_entropy_destroysource(isc_entropysource_t **sourcep);
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Removes an entropy source from the entropy system.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewsisc_entropy_createsamplesource(isc_entropy_t *ent,
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Create an entropy source that consists of samples. Each sample is added
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * to the source via isc_entropy_addsamples(), below.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewsisc_entropy_createcallbacksource(isc_entropy_t *ent,
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Create an entropy source that is polled via a callback. This would
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * be used when keyboard input is used, or a GUI input method. It can
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * also be used to hook in any external entropy source.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Samples are added via isc_entropy_addcallbacksample(), below.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * _addcallbacksample() is the only function which may be called from
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * within an entropy API callback function.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewsisc_entropy_stopcallbacksources(isc_entropy_t *ent);
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Call the stop functions for callback sources that have had their
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * start functions called.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewsisc_entropy_addcallbacksample(isc_entropysource_t *source, isc_uint32_t sample,
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewsisc_entropy_addsample(isc_entropysource_t *source, isc_uint32_t sample,
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Add a sample to the sample source. The sample MUST be a timestamp
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * that increases over time, with the exception of wrap-around for
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * extremely high resolution timers which will quickly wrap-around
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * a 32-bit integer.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * The "extra" parameter is used only to add a bit more unpredictable
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * data. It is not used other than included in the hash of samples.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * When in an entropy API callback function, _addcallbacksource() must be
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * used. At all other times, _addsample() must be used.
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewsisc_entropy_getdata(isc_entropy_t *ent, void *data, unsigned int length,
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Extract data from the entropy pool. This may load the pool from various
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewsisc_entropy_putdata(isc_entropy_t *ent, void *data, unsigned int length,
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Add "length" bytes in "data" to the entropy pool, incrementing the pool's
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * entropy count by "entropy."
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * These bytes will prime the pseudorandom portion even no entropy is actually
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrewsisc_entropy_stats(isc_entropy_t *ent, FILE *out);
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews * Dump some (trivial) stats to the stdio stream "out".
5c526acb82c882e41b655c31f5fa4425c87b671cMark Andrews#endif /* ISC_ENTROPY_H */