2
* Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
2
* Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC")
3
3
* Copyright (C) 2000, 2001 Internet Software Consortium.
5
* Permission to use, copy, modify, and distribute this software for any
5
* Permission to use, copy, modify, and/or distribute this software for any
6
6
* purpose with or without fee is hereby granted, provided that the above
7
7
* copyright notice and this permission notice appear in all copies.
27
/*! \file isc/entropy.h
28
* \brief The entropy API
33
31
* The entropy object is locked internally. All callbacks into
34
32
* application-provided functions (for setup, gathering, and
35
33
* shutdown of sources) are guaranteed to be called with the
36
34
* entropy API lock held. This means these functions are
37
35
* not permitted to call back into the entropy API.
40
38
* No anticipated impact.
43
41
* A buffer, used as an entropy pool.
46
44
* While this code is believed to implement good entropy gathering
47
45
* and distribution, it has not been reviewed by a cryptographic
50
47
* Since the added entropy is only as good as the sources used,
51
48
* this module could hand out bad data and never know it.
63
60
#include <isc/lang.h>
64
61
#include <isc/types.h>
67
* Entropy callback function.
64
/*% Entropy callback function. */
69
65
typedef isc_result_t (*isc_entropystart_t)(isc_entropysource_t *source,
70
66
void *arg, isc_boolean_t blocking);
71
67
typedef isc_result_t (*isc_entropyget_t)(isc_entropysource_t *source,
72
68
void *arg, isc_boolean_t blocking);
73
69
typedef void (*isc_entropystop_t)(isc_entropysource_t *source, void *arg);
81
78
* Extract only "good" data; return failure if there is not enough
82
79
* data available and there are no sources which we can poll to get
83
80
* data, or those sources are empty.
84
#define ISC_ENTROPY_GOODONLY 0x00000001U
86
87
* Extract as much good data as possible, but if there isn't enough
87
88
* at hand, return what is available. This flag only makes sense
88
89
* when used with _GOODONLY.
91
#define ISC_ENTROPY_PARTIAL 0x00000002U
91
94
* Block the task until data is available. This is contrary to the
92
95
* ISC task system, where tasks should never block. However, if
93
96
* this is a special purpose application where blocking a task is
95
98
* This flag only makes sense when used with _GOODONLY, and will
96
99
* block regardless of the setting for _PARTIAL.
98
#define ISC_ENTROPY_GOODONLY 0x00000001U
99
#define ISC_ENTROPY_PARTIAL 0x00000002U
100
101
#define ISC_ENTROPY_BLOCKING 0x00000004U
104
105
* Estimate the amount of entropy contained in the sample pool.
105
106
* If this is not set, the source will be gathered and perodically
106
107
* mixed into the entropy pool, but no increment in contained entropy
112
113
* For use with isc_entropy_usebestsource().
115
117
* Use the keyboard as the only entropy source.
119
#define ISC_ENTROPY_KEYBOARDYES 1
117
122
* Never use the keyboard as an entropy source.
124
#define ISC_ENTROPY_KEYBOARDNO 2
119
127
* Use the keyboard as an entropy source only if opening the
120
128
* random device fails.
122
#define ISC_ENTROPY_KEYBOARDYES 1
123
#define ISC_ENTROPY_KEYBOARDNO 2
124
130
#define ISC_ENTROPY_KEYBOARDMAYBE 3
126
132
ISC_LANG_BEGINDECLS
133
139
isc_entropy_create(isc_mem_t *mctx, isc_entropy_t **entp);
135
* Create a new entropy object.
141
* \brief Create a new entropy object.
139
145
isc_entropy_attach(isc_entropy_t *ent, isc_entropy_t **entp);
141
147
* Attaches to an entropy object.
145
151
isc_entropy_detach(isc_entropy_t **entp);
147
* Detaches from an entropy object.
153
* \brief Detaches from an entropy object.
151
157
isc_entropy_createfilesource(isc_entropy_t *ent, const char *fname);
153
* Create a new entropy source from a file.
159
* \brief Create a new entropy source from a file.
155
161
* The file is assumed to contain good randomness, and will be mixed directly
156
162
* into the pool with every byte adding 8 bits of entropy.
170
176
isc_entropy_destroysource(isc_entropysource_t **sourcep);
172
* Removes an entropy source from the entropy system.
178
* \brief Removes an entropy source from the entropy system.
176
182
isc_entropy_createsamplesource(isc_entropy_t *ent,
177
183
isc_entropysource_t **sourcep);
179
* Create an entropy source that consists of samples. Each sample is added
185
* \brief Create an entropy source that consists of samples. Each sample is added
180
186
* to the source via isc_entropy_addsamples(), below.
187
193
isc_entropystop_t stop,
189
195
isc_entropysource_t **sourcep);
191
* Create an entropy source that is polled via a callback. This would
197
* \brief Create an entropy source that is polled via a callback.
192
200
* be used when keyboard input is used, or a GUI input method. It can
193
201
* also be used to hook in any external entropy source.
201
209
isc_entropy_stopcallbacksources(isc_entropy_t *ent);
203
* Call the stop functions for callback sources that have had their
211
* \brief Call the stop functions for callback sources that have had their
204
212
* start functions called.
208
217
isc_entropy_addcallbacksample(isc_entropysource_t *source, isc_uint32_t sample,
209
218
isc_uint32_t extra);
211
220
isc_entropy_addsample(isc_entropysource_t *source, isc_uint32_t sample,
212
221
isc_uint32_t extra);
214
* Add a sample to the sample source. The sample MUST be a timestamp
223
* \brief Add a sample to the sample source.
225
* The sample MUST be a timestamp
215
226
* that increases over time, with the exception of wrap-around for
216
227
* extremely high resolution timers which will quickly wrap-around
217
228
* a 32-bit integer.
222
233
* When in an entropy API callback function, _addcallbacksource() must be
223
234
* used. At all other times, _addsample() must be used.
227
239
isc_entropy_getdata(isc_entropy_t *ent, void *data, unsigned int length,
228
240
unsigned int *returned, unsigned int flags);
230
* Extract data from the entropy pool. This may load the pool from various
242
* \brief Extract data from the entropy pool. This may load the pool from various
245
* Do this by stiring the pool and returning a part of hash as randomness.
246
* Note that no secrets are given away here since parts of the hash are
247
* xored together before returned.
249
* Honor the request from the caller to only return good data, any data,
235
254
isc_entropy_putdata(isc_entropy_t *ent, void *data, unsigned int length,
236
255
isc_uint32_t entropy);
238
* Add "length" bytes in "data" to the entropy pool, incrementing the pool's
257
* \brief Add "length" bytes in "data" to the entropy pool, incrementing the pool's
239
258
* entropy count by "entropy."
241
260
* These bytes will prime the pseudorandom portion even no entropy is actually
246
265
isc_entropy_stats(isc_entropy_t *ent, FILE *out);
267
* \brief Dump some (trivial) stats to the stdio stream "out".
271
isc_entropy_status(isc_entropy_t *end);
248
* Dump some (trivial) stats to the stdio stream "out".
273
* Returns the number of bits the pool currently contains. This is just
252
278
isc_entropy_usebestsource(isc_entropy_t *ectx, isc_entropysource_t **source,
253
279
const char *randomfile, int use_keyboard);
255
* Use whatever source of entropy is best.
281
* \brief Use whatever source of entropy is best.
258
* If "randomfile" is not NULL, open it with
284
*\li If "randomfile" is not NULL, open it with
259
285
* isc_entropy_createfilesource().
261
* If "randomfile" is NULL and the system's random device was detected
287
*\li If "randomfile" is NULL and the system's random device was detected
262
288
* when the program was configured and built, open that device with
263
289
* isc_entropy_createfilesource().
265
* If "use_keyboard" is ISC_ENTROPY_KEYBOARDYES, then always open
291
*\li If "use_keyboard" is #ISC_ENTROPY_KEYBOARDYES, then always open
266
292
* the keyboard as an entropy source (possibly in addition to
267
293
* "randomfile" or the random device).
269
* If "use_keyboard" is ISC_ENTROPY_KEYBOARDMAYBE, open the keyboard only
295
*\li If "use_keyboard" is #ISC_ENTROPY_KEYBOARDMAYBE, open the keyboard only
270
296
* if opening the random file/device fails. A message will be
271
297
* printed describing the need for keyboard input.
273
* If "use_keyboard" is ISC_ENTROPY_KEYBOARDNO, the keyboard will
299
*\li If "use_keyboard" is #ISC_ENTROPY_KEYBOARDNO, the keyboard will
274
300
* never be opened.
277
* ISC_R_SUCCESS if at least one source of entropy could be started.
303
*\li #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
305
*\li #ISC_R_NOENTROPY if use_keyboard is #ISC_ENTROPY_KEYBOARDNO and
280
306
* there is no random device pathname compiled into the program.
282
* A return code from isc_entropy_createfilesource() or
308
*\li A return code from isc_entropy_createfilesource() or
283
309
* isc_entropy_createcallbacksource().
added
removed
lib/isc/include/isc/entropy.h
