/* -*-c-*-
*
- * $Id: rand.h,v 1.2 1999/10/12 21:00:15 mdw Exp $
+ * $Id: rand.h,v 1.8 2001/02/03 16:07:33 mdw Exp $
*
* Secure random number generator
*
/*----- Revision history --------------------------------------------------*
*
* $Log: rand.h,v $
+ * Revision 1.8 2001/02/03 16:07:33 mdw
+ * Give generic random objects separate namespaces for their supported misc
+ * ops.
+ *
+ * Revision 1.7 2000/10/08 12:07:18 mdw
+ * Remove spurious comma in enum.
+ *
+ * Revision 1.6 2000/06/17 11:53:38 mdw
+ * Deprecate `rand_getgood'. Provide a new interface to ensure that a pool
+ * is well seeded.
+ *
+ * Revision 1.5 1999/12/13 15:34:15 mdw
+ * Fix a typo.
+ *
+ * Revision 1.4 1999/12/10 23:29:48 mdw
+ * Change header file guard names.
+ *
+ * Revision 1.3 1999/10/15 21:04:30 mdw
+ * Increase output buffer a bit for performance.
+ *
* Revision 1.2 1999/10/12 21:00:15 mdw
* Make pool and buffer sizes more sensible.
*
* concerns I expressed about the Linux generator in a Usenet article to
* sci.crypt.
*
- * The generator is divided into two parts: an input pool and an outpu
+ * The generator is divided into two parts: an input pool and an output
* buffer. New random data is placed into the pool in the way described
* below, which is shamelessly stolen from the Linux /dev/random generator.
* The only interaction that the pool has on the output buffer is through the
* an adversary has to guess before predicting generator output.
*/
-#ifndef RAND_H
-#define RAND_H
+#ifndef CATACOMB_RAND_H
+#define CATACOMB_RAND_H
#ifdef __cplusplus
extern "C" {
#include <stddef.h>
-#include "rmd160-hmac.h"
+#ifndef CATACOMB_GRAND_H
+# include "grand.h"
+#endif
+
+#ifndef CATACOMB_RMD160_HMAC_H
+# include "rmd160-hmac.h"
+#endif
/*----- Magic numbers -----------------------------------------------------*/
#define RAND_POOLSZ 128 /* Input pool size in bytes */
-#define RAND_BUFSZ 128 /* Output buffer size in bytes */
+#define RAND_BUFSZ 512 /* Output buffer size in bytes */
#define RAND_SECSZ 20 /* Secret octets in output buffer */
#define RAND_IBITS (RAND_POOLSZ * 8)
extern void rand_noisesrc(rand_pool */*r*/, const rand_source */*s*/);
+/* --- @rand_seed@ --- *
+ *
+ * Arguments: @rand_pool *r@ = pointer to a randomness pool
+ * @unsigned bits@ = number of bits to ensure
+ *
+ * Returns: ---
+ *
+ * Use: Ensures that there are at least @bits@ good bits of entropy
+ * in the pool. It is recommended that you call this after
+ * initializing a new pool. Requesting @bits > RAND_IBITS@ is
+ * doomed to failure (and is an error).
+ */
+
+extern void rand_seed(rand_pool */*r*/, unsigned /*bits*/);
+
/* --- @rand_key@ --- *
*
* Arguments: @rand_pool *r@ = pointer to a randomness pool
* Use: Gets random data from the pool. The pool's contents can't be
* determined from the output of this function; nor can the
* output data be determined from a knowledge of the data input
- * to the pool wihtout also having knowledge of the secret key.
+ * to the pool without also having knowledge of the secret key.
* The good bits counter is decremented, although no special
* action is taken if it reaches zero.
*/
extern void rand_getgood(rand_pool */*r*/, void */*p*/, size_t /*sz*/);
+/*----- Generic random number generator interface -------------------------*/
+
+/* --- Miscellaneous operations --- */
+
+enum {
+ RAND_GATE = GRAND_SPECIFIC('R'), /* No args */
+ RAND_STRETCH, /* No args */
+ RAND_KEY, /* @const void *k, size_t sz@ */
+ RAND_NOISESRC, /* @const rand_source *s@ */
+ RAND_SEED /* @unsigned bits@ */
+};
+
+/* --- Default random number generator --- */
+
+extern grand rand_global;
+
+/* --- @rand_create@ --- *
+ *
+ * Arguments: ---
+ *
+ * Returns: Pointer to a generic generator.
+ *
+ * Use: Constructs a generic generator interface over a Catacomb
+ * entropy pool generator.
+ */
+
+extern grand *rand_create(void);
+
/*----- That's all, folks -------------------------------------------------*/
#ifdef __cplusplus