document functions. Add isc_lfsr_init() and unimplemented isc_lfsr_findlfsr()

lib/isc/include/isc/lfsr.h

@@ -26,7 +26,7 @@
  */
 typedef struct {
 	isc_uint32_t	state;	/* previous state */
-	isc_uint32_t	bits;	/* length */
+	unsigned int	bits;	/* length */
 	isc_uint32_t	tap;	/* bit taps */
 } isc_lfsr_t;
 
@@ -39,10 +39,81 @@ extern isc_lfsr_t isc_lfsr_standard[];
 
 ISC_LANG_BEGINDECLS
 
+/*
+ * In all these functions it is important that the caller only use as many
+ * bits as the LFSR has state.  Also, it isn't guaranteed that an LFSR of
+ * bit length 32 will have 2^32 unique states before repeating.
+ */
+
+isc_lfsr_t *isc_lfsr_findlfsr(unsigned int bits);
+/*
+ * Find an LFSR that has at least "bits" of state.
+ *
+ * Requires:
+ *
+ *	8 <= bits <= 32
+ *
+ * Returns:
+ *
+ *	NULL if no LFSR can be found.
+ *
+ *	If NON-null, it points to the first LFSR in the standard LFSR table
+ *	that satisfies the requirements.
+ */
+
+void isc_lfsr_init(isc_lfsr_t *lfsr, isc_uint32_t state, unsigned int bits,
+		   isc_uint32_t tap);
+/*
+ * Initialize an LFSR.
+ *
+ * Note:
+ *
+ *	Putting untrusted values into this function will cause the LFSR to
+ *	generate (perhaps) non-maximal length sequences.
+ *
+ * Requires:
+ *
+ *	lfsr != NULL
+ *
+ *	8 <= bits <= 32
+ *
+ *	tap != 0
+ */
+
 isc_uint32_t isc_lfsr_generate(isc_lfsr_t *lfsr);
+/*
+ * Return the next state in the LFSR.
+ *
+ * Requires:
+ *
+ *	lfsr be valid.
+ */
+
 isc_uint32_t isc_lfsr_skipgenerate(isc_lfsr_t *lfsr, unsigned int skip);
+/*
+ * Skip "skip" states, then return the next state after that.
+ *
+ * Requiremens are the same as for isc_lfsr_generate(), above.
+ */
+
 isc_uint32_t isc_lfsr_lfsrskipgenerate(isc_lfsr_t *lfsr1, isc_lfsr_t *lfsr2,
 				       unsigned int skipbits);
+/*
+ * Given two LFSRs, use the current state from each to skip entries in the
+ * other.  The next states are then xor'd together and returned.
+ *
+ * Notes:
+ *
+ *	Since the current state from each of the LFSRs is used to skip
+ *	state in the other, it is important that no state be leaked
+ *	from either LFSR.
+ *
+ * Requires:
+ *
+ *	lfsr1 and lfsr2 be valid.
+ *
+ *	1 <= skipbits <= 31
+ */
 
 ISC_LANG_ENDDECLS
 

lib/isc/lfsr.c

@@ -23,6 +23,7 @@
 /*
  * Any LFSR added to this table needs to have a large period.
  * Entries should be added from longest bit state to smallest bit state.
+ * XXXMLG Need to pull some from Applied Crypto.
  */
 isc_lfsr_t isc_lfsr_standard[] = {
 	{ 0, 32, 0x80000057U },	/* 32-bit, x^31 + x^6 + x^4 + x^2 + x + 1 */
@@ -35,6 +36,25 @@ isc_lfsr_t isc_lfsr_standard[] = {
 
 #define VALID_LFSR(x)	(x != NULL)
 
+isc_lfsr_t *
+isc_lfsr_findlfsr(unsigned int bits)
+{
+	return (NULL);  /* XXXMLG implement? */
+}
+
+void
+isc_lfsr_init(isc_lfsr_t *lfsr, isc_uint32_t state, unsigned int bits,
+	      isc_uint32_t tap)
+{
+	REQUIRE(VALID_LFSR(lfsr));
+	REQUIRE(8 <= bits && bits <= 32);
+	REQUIRE(tap != 0);
+
+	lfsr->state = state;
+	lfsr->bits = bits;
+	lfsr->tap = tap;
+}
+
 /*
  * Return the next state of the lfsr.
  */