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