lfsr.h

Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
00003  * Copyright (C) 1999-2001  Internet Software Consortium.
00004  *
00005  * Permission to use, copy, modify, and/or distribute this software for any
00006  * purpose with or without fee is hereby granted, provided that the above
00007  * copyright notice and this permission notice appear in all copies.
00008  *
00009  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
00010  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
00011  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
00012  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
00013  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
00014  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
00015  * PERFORMANCE OF THIS SOFTWARE.
00016  */
00017 
00018 /* $Id: lfsr.h,v 1.17 2007/06/19 23:47:18 tbox Exp $ */
00019 
00020 #ifndef ISC_LFSR_H
00021 #define ISC_LFSR_H 1
00022 
00023 /*! \file isc/lfsr.h */
00024 
00025 #include <isc/lang.h>
00026 #include <isc/types.h>
00027 
00028 typedef struct isc_lfsr isc_lfsr_t;
00029 
00030 /*%
00031  * This function is called when reseeding is needed.  It is allowed to
00032  * modify any state in the LFSR in any way it sees fit OTHER THAN "bits".
00033  *
00034  * It MUST set "count" to a new value or the lfsr will never reseed again.
00035  *
00036  * Also, a reseed will never occur in the middle of an extraction.  This
00037  * is purely an optimization, and is probably what one would want.
00038  */
00039 typedef void (*isc_lfsrreseed_t)(isc_lfsr_t *, void *);
00040 
00041 /*%
00042  * The members of this structure can be used by the application, but care
00043  * needs to be taken to not change state once the lfsr is in operation.
00044  */
00045 struct isc_lfsr {
00046         isc_uint32_t            state;  /*%< previous state */
00047         unsigned int            bits;   /*%< length */
00048         isc_uint32_t            tap;    /*%< bit taps */
00049         unsigned int            count;  /*%< reseed count (in BITS!) */
00050         isc_lfsrreseed_t        reseed; /*%< reseed function */
00051         void                   *arg;    /*%< reseed function argument */
00052 };
00053 
00054 ISC_LANG_BEGINDECLS
00055 
00056 
00057 void 
00058 isc_lfsr_init(isc_lfsr_t *lfsr, isc_uint32_t state, unsigned int bits,
00059                    isc_uint32_t tap, unsigned int count,
00060                    isc_lfsrreseed_t reseed, void *arg);
00061 /*%<
00062  * Initialize an LFSR.
00063  *
00064  * Note:
00065  *
00066  *\li   Putting untrusted values into this function will cause the LFSR to
00067  *      generate (perhaps) non-maximal length sequences.
00068  *
00069  * Requires:
00070  *
00071  *\li   lfsr != NULL
00072  *
00073  *\li   8 <= bits <= 32
00074  *
00075  *\li   tap != 0
00076  */
00077 
00078 void 
00079 isc_lfsr_generate(isc_lfsr_t *lfsr, void *data, unsigned int count);
00080 /*%<
00081  * Returns "count" bytes of data from the LFSR.
00082  *
00083  * Requires:
00084  *
00085  *\li   lfsr be valid.
00086  *
00087  *\li   data != NULL.
00088  *
00089  *\li   count > 0.
00090  */
00091 
00092 void 
00093 isc_lfsr_skip(isc_lfsr_t *lfsr, unsigned int skip);
00094 /*%<
00095  * Skip "skip" states.
00096  *
00097  * Requires:
00098  *
00099  *\li   lfsr be valid.
00100  */
00101 
00102 isc_uint32_t 
00103 isc_lfsr_generate32(isc_lfsr_t *lfsr1, isc_lfsr_t *lfsr2);
00104 /*%<
00105  * Given two LFSRs, use the current state from each to skip entries in the
00106  * other.  The next states are then xor'd together and returned.
00107  *
00108  * WARNING:
00109  *
00110  *\li   This function is used only for very, very low security data, such
00111  *      as DNS message IDs where it is desired to have an unpredictable
00112  *      stream of bytes that are harder to predict than a simple flooding
00113  *      attack.
00114  *
00115  * Notes:
00116  *
00117  *\li   Since the current state from each of the LFSRs is used to skip
00118  *      state in the other, it is important that no state be leaked
00119  *      from either LFSR.
00120  *
00121  * Requires:
00122  *
00123  *\li   lfsr1 and lfsr2 be valid.
00124  *
00125  *\li   1 <= skipbits <= 31
00126  */
00127 
00128 ISC_LANG_ENDDECLS
00129 
00130 #endif /* ISC_LFSR_H */

Generated on Tue Apr 28 17:41:04 2015 by Doxygen 1.5.4 for BIND9 Internals 9.11.0pre-alpha