contrib/bind-9.3/lib/isc/include/isc/entropy.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000, 2001  Internet Software Consortium.
   4  *
   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.
   8  *
   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.
  16  */
  17
  18 /* $Id: entropy.h,v 1.23.2.1.10.1 2004/03/06 08:14:40 marka Exp $ */
  19
  20 #ifndef ISC_ENTROPY_H
  21 #define ISC_ENTROPY_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*
  28  * Entropy
  29  *
  30  * The entropy API
  31  *
  32  * MP:
  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.
  38  *
  39  * Reliability:
  40  *      No anticipated impact.
  41  *
  42  * Resources:
  43  *      A buffer, used as an entropy pool.
  44  *
  45  * Security:
  46  *      While this code is believed to implement good entropy gathering
  47  *      and distribution, it has not been reviewed by a cryptographic
  48  *      expert.
  49  *
  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.
  52  *
  53  * Standards:
  54  *      None.
  55  */
  56
  57 /***
  58  *** Imports
  59  ***/
  60
  61 #include <stdio.h>
  62
  63 #include <isc/lang.h>
  64 #include <isc/types.h>
  65
  66 /*
  67  * Entropy callback function.
  68  */
  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);
  74
  75 /***
  76  *** Flags.
  77  ***/
  78
  79 /*
  80  * _GOODONLY
  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.
  84  *
  85  * _PARTIAL
  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.
  89  *
  90  * _BLOCKING
  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.
  97  */
  98 #define ISC_ENTROPY_GOODONLY    0x00000001U
  99 #define ISC_ENTROPY_PARTIAL     0x00000002U
 100 #define ISC_ENTROPY_BLOCKING    0x00000004U
 101
 102 /*
 103  * _ESTIMATE
 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.
 108  */
 109 #define ISC_ENTROPYSOURCE_ESTIMATE      0x00000001U
 110
 111 /*
 112  * For use with isc_entropy_usebestsource().
 113  *
 114  * _KEYBOARDYES
 115  *      Use the keyboard as the only entropy source.
 116  * _KEYBOARDNO
 117  *      Never use the keyboard as an entropy source.
 118  * _KEYBOARDMAYBE
 119  *      Use the keyboard as an entropy source only if opening the
 120  *      random device fails.
 121  */
 122 #define ISC_ENTROPY_KEYBOARDYES         1
 123 #define ISC_ENTROPY_KEYBOARDNO          2
 124 #define ISC_ENTROPY_KEYBOARDMAYBE       3
 125
 126 ISC_LANG_BEGINDECLS
 127
 128 /***
 129  *** Functions
 130  ***/
 131
 132 isc_result_t
 133 isc_entropy_create(isc_mem_t *mctx, isc_entropy_t **entp);
 134 /*
 135  * Create a new entropy object.
 136  */
 137
 138 void
 139 isc_entropy_attach(isc_entropy_t *ent, isc_entropy_t **entp);
 140 /*
 141  * Attaches to an entropy object.
 142  */
 143
 144 void
 145 isc_entropy_detach(isc_entropy_t **entp);
 146 /*
 147  * Detaches from an entropy object.
 148  */
 149
 150 isc_result_t
 151 isc_entropy_createfilesource(isc_entropy_t *ent, const char *fname);
 152 /*
 153  * Create a new entropy source from a file.
 154  *
 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.
 157  *
 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.
 163  *
 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.
 167  */
 168
 169 void
 170 isc_entropy_destroysource(isc_entropysource_t **sourcep);
 171 /*
 172  * Removes an entropy source from the entropy system.
 173  */
 174
 175 isc_result_t
 176 isc_entropy_createsamplesource(isc_entropy_t *ent,
 177                                isc_entropysource_t **sourcep);
 178 /*
 179  * Create an entropy source that consists of samples.  Each sample is added
 180  * to the source via isc_entropy_addsamples(), below.
 181  */
 182
 183 isc_result_t
 184 isc_entropy_createcallbacksource(isc_entropy_t *ent,
 185                                  isc_entropystart_t start,
 186                                  isc_entropyget_t get,
 187                                  isc_entropystop_t stop,
 188                                  void *arg,
 189                                  isc_entropysource_t **sourcep);
 190 /*
 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.
 194  *
 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.
 198  */
 199
 200 void
 201 isc_entropy_stopcallbacksources(isc_entropy_t *ent);
 202 /*
 203  * Call the stop functions for callback sources that have had their
 204  * start functions called.
 205  */
 206
 207 isc_result_t
 208 isc_entropy_addcallbacksample(isc_entropysource_t *source, isc_uint32_t sample,
 209                               isc_uint32_t extra);
 210 isc_result_t
 211 isc_entropy_addsample(isc_entropysource_t *source, isc_uint32_t sample,
 212                       isc_uint32_t extra);
 213 /*
 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
 217  * a 32-bit integer.
 218  *
 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.
 221  *
 222  * When in an entropy API callback function, _addcallbacksource() must be
 223  * used.  At all other times, _addsample() must be used.
 224  */
 225
 226 isc_result_t
 227 isc_entropy_getdata(isc_entropy_t *ent, void *data, unsigned int length,
 228                     unsigned int *returned, unsigned int flags);
 229 /*
 230  * Extract data from the entropy pool.  This may load the pool from various
 231  * sources.
 232  */
 233
 234 void
 235 isc_entropy_putdata(isc_entropy_t *ent, void *data, unsigned int length,
 236                     isc_uint32_t entropy);
 237 /*
 238  * Add "length" bytes in "data" to the entropy pool, incrementing the pool's
 239  * entropy count by "entropy."
 240  *
 241  * These bytes will prime the pseudorandom portion even no entropy is actually
 242  * added.
 243  */
 244
 245 void
 246 isc_entropy_stats(isc_entropy_t *ent, FILE *out);
 247 /*
 248  * Dump some (trivial) stats to the stdio stream "out".
 249  */
 250
 251 isc_result_t
 252 isc_entropy_usebestsource(isc_entropy_t *ectx, isc_entropysource_t **source,
 253                           const char *randomfile, int use_keyboard);
 254 /*
 255  * Use whatever source of entropy is best.
 256  *
 257  * Notes:
 258  *      If "randomfile" is not NULL, open it with
 259  *      isc_entropy_createfilesource().
 260  *
 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().
 264  *
 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).
 268  *
 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.
 272  *
 273  *      If "use_keyboard" is ISC_ENTROPY_KEYBOARDNO, the keyboard will
 274  *      never be opened.
 275  *
 276  * Returns:
 277  *      ISC_R_SUCCESS if at least one source of entropy could be started.
 278  *
 279  *      ISC_R_NOENTROPY if use_keyboard is ISC_ENTROPY_KEYBOARDNO and
 280  *      there is no random device pathname compiled into the program.
 281  *
 282  *      A return code from isc_entropy_createfilesource() or
 283  *      isc_entropy_createcallbacksource().
 284  */
 285
 286 ISC_LANG_ENDDECLS
 287
 288 #endif /* ISC_ENTROPY_H */