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

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-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: lfsr.h,v 1.10.206.1 2004/03/06 08:14:43 marka Exp $ */
  19
  20 #ifndef ISC_LFSR_H
  21 #define ISC_LFSR_H 1
  22
  23 #include <isc/lang.h>
  24 #include <isc/types.h>
  25
  26 typedef struct isc_lfsr isc_lfsr_t;
  27
  28 /*
  29  * This function is called when reseeding is needed.  It is allowed to
  30  * modify any state in the LFSR in any way it sees fit OTHER THAN "bits".
  31  *
  32  * It MUST set "count" to a new value or the lfsr will never reseed again.
  33  *
  34  * Also, a reseed will never occur in the middle of an extraction.  This
  35  * is purely an optimization, and is probably what one would want.
  36  */
  37 typedef void (*isc_lfsrreseed_t)(isc_lfsr_t *, void *);
  38
  39 /*
  40  * The members of this structure can be used by the application, but care
  41  * needs to be taken to not change state once the lfsr is in operation.
  42  */
  43 struct isc_lfsr {
  44         isc_uint32_t            state;  /* previous state */
  45         unsigned int            bits;   /* length */
  46         isc_uint32_t            tap;    /* bit taps */
  47         unsigned int            count;  /* reseed count (in BITS!) */
  48         isc_lfsrreseed_t        reseed; /* reseed function */
  49         void                   *arg;    /* reseed function argument */
  50 };
  51
  52 ISC_LANG_BEGINDECLS
  53
  54 /*
  55  * In all these functions it is important that the caller only use as many
  56  * bits as the LFSR has state.  Also, it isn't guaranteed that an LFSR of
  57  * bit length 32 will have 2^32 unique states before repeating.
  58  */
  59
  60 void
  61 isc_lfsr_init(isc_lfsr_t *lfsr, isc_uint32_t state, unsigned int bits,
  62                    isc_uint32_t tap, unsigned int count,
  63                    isc_lfsrreseed_t reseed, void *arg);
  64 /*
  65  * Initialize an LFSR.
  66  *
  67  * Note:
  68  *
  69  *      Putting untrusted values into this function will cause the LFSR to
  70  *      generate (perhaps) non-maximal length sequences.
  71  *
  72  * Requires:
  73  *
  74  *      lfsr != NULL
  75  *
  76  *      8 <= bits <= 32
  77  *
  78  *      tap != 0
  79  */
  80
  81 void
  82 isc_lfsr_generate(isc_lfsr_t *lfsr, void *data, unsigned int count);
  83 /*
  84  * Returns "count" bytes of data from the LFSR.
  85  *
  86  * Requires:
  87  *
  88  *      lfsr be valid.
  89  *
  90  *      data != NULL.
  91  *
  92  *      count > 0.
  93  */
  94
  95 void
  96 isc_lfsr_skip(isc_lfsr_t *lfsr, unsigned int skip);
  97 /*
  98  * Skip "skip" states.
  99  *
 100  * Requires:
 101  *
 102  *      lfsr be valid.
 103  */
 104
 105 isc_uint32_t
 106 isc_lfsr_generate32(isc_lfsr_t *lfsr1, isc_lfsr_t *lfsr2);
 107 /*
 108  * Given two LFSRs, use the current state from each to skip entries in the
 109  * other.  The next states are then xor'd together and returned.
 110  *
 111  * WARNING:
 112  *
 113  *      This function is used only for very, very low security data, such
 114  *      as DNS message IDs where it is desired to have an unpredictable
 115  *      stream of bytes that are harder to predict than a simple flooding
 116  *      attack.
 117  *
 118  * Notes:
 119  *
 120  *      Since the current state from each of the LFSRs is used to skip
 121  *      state in the other, it is important that no state be leaked
 122  *      from either LFSR.
 123  *
 124  * Requires:
 125  *
 126  *      lfsr1 and lfsr2 be valid.
 127  *
 128  *      1 <= skipbits <= 31
 129  */
 130
 131 ISC_LANG_ENDDECLS
 132
 133 #endif /* ISC_LFSR_H */