2 * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 2000, 2001 Internet Software Consortium.
5 * Permission to use, copy, modify, and distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
18 /* $Id: entropy.h,v 1.23.2.1.10.1 2004/03/06 08:14:40 marka Exp $ */
21 #define ISC_ENTROPY_H 1
33 * The entropy object is locked internally. All callbacks into
34 * application-provided functions (for setup, gathering, and
35 * shutdown of sources) are guaranteed to be called with the
36 * entropy API lock held. This means these functions are
37 * not permitted to call back into the entropy API.
40 * No anticipated impact.
43 * A buffer, used as an entropy pool.
46 * While this code is believed to implement good entropy gathering
47 * and distribution, it has not been reviewed by a cryptographic
50 * Since the added entropy is only as good as the sources used,
51 * this module could hand out bad data and never know it.
64 #include <isc/types.h>
67 * Entropy callback function.
69 typedef isc_result_t (*isc_entropystart_t)(isc_entropysource_t *source,
70 void *arg, isc_boolean_t blocking);
71 typedef isc_result_t (*isc_entropyget_t)(isc_entropysource_t *source,
72 void *arg, isc_boolean_t blocking);
73 typedef void (*isc_entropystop_t)(isc_entropysource_t *source, void *arg);
81 * Extract only "good" data; return failure if there is not enough
82 * data available and there are no sources which we can poll to get
83 * data, or those sources are empty.
86 * Extract as much good data as possible, but if there isn't enough
87 * at hand, return what is available. This flag only makes sense
88 * when used with _GOODONLY.
91 * Block the task until data is available. This is contrary to the
92 * ISC task system, where tasks should never block. However, if
93 * this is a special purpose application where blocking a task is
94 * acceptable (say, an offline zone signer) this flag may be set.
95 * This flag only makes sense when used with _GOODONLY, and will
96 * block regardless of the setting for _PARTIAL.
98 #define ISC_ENTROPY_GOODONLY 0x00000001U
99 #define ISC_ENTROPY_PARTIAL 0x00000002U
100 #define ISC_ENTROPY_BLOCKING 0x00000004U
104 * Estimate the amount of entropy contained in the sample pool.
105 * If this is not set, the source will be gathered and perodically
106 * mixed into the entropy pool, but no increment in contained entropy
107 * will be assumed. This flag only makes sense on sample sources.
109 #define ISC_ENTROPYSOURCE_ESTIMATE 0x00000001U
112 * For use with isc_entropy_usebestsource().
115 * Use the keyboard as the only entropy source.
117 * Never use the keyboard as an entropy source.
119 * Use the keyboard as an entropy source only if opening the
120 * random device fails.
122 #define ISC_ENTROPY_KEYBOARDYES 1
123 #define ISC_ENTROPY_KEYBOARDNO 2
124 #define ISC_ENTROPY_KEYBOARDMAYBE 3
133 isc_entropy_create(isc_mem_t *mctx, isc_entropy_t **entp);
135 * Create a new entropy object.
139 isc_entropy_attach(isc_entropy_t *ent, isc_entropy_t **entp);
141 * Attaches to an entropy object.
145 isc_entropy_detach(isc_entropy_t **entp);
147 * Detaches from an entropy object.
151 isc_entropy_createfilesource(isc_entropy_t *ent, const char *fname);
153 * Create a new entropy source from a file.
155 * The file is assumed to contain good randomness, and will be mixed directly
156 * into the pool with every byte adding 8 bits of entropy.
158 * The file will be put into non-blocking mode, so it may be a device file,
159 * such as /dev/random. /dev/urandom should not be used here if it can
160 * be avoided, since it will always provide data even if it isn't good.
161 * We will make as much pseudorandom data as we need internally if our
162 * caller asks for it.
164 * If we hit end-of-file, we will stop reading from this source. Callers
165 * who require strong random data will get failure when our pool drains.
166 * The file will never be opened/read again once EOF is reached.
170 isc_entropy_destroysource(isc_entropysource_t **sourcep);
172 * Removes an entropy source from the entropy system.
176 isc_entropy_createsamplesource(isc_entropy_t *ent,
177 isc_entropysource_t **sourcep);
179 * Create an entropy source that consists of samples. Each sample is added
180 * to the source via isc_entropy_addsamples(), below.
184 isc_entropy_createcallbacksource(isc_entropy_t *ent,
185 isc_entropystart_t start,
186 isc_entropyget_t get,
187 isc_entropystop_t stop,
189 isc_entropysource_t **sourcep);
191 * Create an entropy source that is polled via a callback. This would
192 * be used when keyboard input is used, or a GUI input method. It can
193 * also be used to hook in any external entropy source.
195 * Samples are added via isc_entropy_addcallbacksample(), below.
196 * _addcallbacksample() is the only function which may be called from
197 * within an entropy API callback function.
201 isc_entropy_stopcallbacksources(isc_entropy_t *ent);
203 * Call the stop functions for callback sources that have had their
204 * start functions called.
208 isc_entropy_addcallbacksample(isc_entropysource_t *source, isc_uint32_t sample,
211 isc_entropy_addsample(isc_entropysource_t *source, isc_uint32_t sample,
214 * Add a sample to the sample source. The sample MUST be a timestamp
215 * that increases over time, with the exception of wrap-around for
216 * extremely high resolution timers which will quickly wrap-around
219 * The "extra" parameter is used only to add a bit more unpredictable
220 * data. It is not used other than included in the hash of samples.
222 * When in an entropy API callback function, _addcallbacksource() must be
223 * used. At all other times, _addsample() must be used.
227 isc_entropy_getdata(isc_entropy_t *ent, void *data, unsigned int length,
228 unsigned int *returned, unsigned int flags);
230 * Extract data from the entropy pool. This may load the pool from various
235 isc_entropy_putdata(isc_entropy_t *ent, void *data, unsigned int length,
236 isc_uint32_t entropy);
238 * Add "length" bytes in "data" to the entropy pool, incrementing the pool's
239 * entropy count by "entropy."
241 * These bytes will prime the pseudorandom portion even no entropy is actually
246 isc_entropy_stats(isc_entropy_t *ent, FILE *out);
248 * Dump some (trivial) stats to the stdio stream "out".
252 isc_entropy_usebestsource(isc_entropy_t *ectx, isc_entropysource_t **source,
253 const char *randomfile, int use_keyboard);
255 * Use whatever source of entropy is best.
258 * If "randomfile" is not NULL, open it with
259 * isc_entropy_createfilesource().
261 * If "randomfile" is NULL and the system's random device was detected
262 * when the program was configured and built, open that device with
263 * isc_entropy_createfilesource().
265 * If "use_keyboard" is ISC_ENTROPY_KEYBOARDYES, then always open
266 * the keyboard as an entropy source (possibly in addition to
267 * "randomfile" or the random device).
269 * If "use_keyboard" is ISC_ENTROPY_KEYBOARDMAYBE, open the keyboard only
270 * if opening the random file/device fails. A message will be
271 * printed describing the need for keyboard input.
273 * If "use_keyboard" is ISC_ENTROPY_KEYBOARDNO, the keyboard will
277 * ISC_R_SUCCESS if at least one source of entropy could be started.
279 * ISC_R_NOENTROPY if use_keyboard is ISC_ENTROPY_KEYBOARDNO and
280 * there is no random device pathname compiled into the program.
282 * A return code from isc_entropy_createfilesource() or
283 * isc_entropy_createcallbacksource().
288 #endif /* ISC_ENTROPY_H */