X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/ba6e6b64033b1f9de49feccb5c9cd438354481f7..0f00dc4c8eb47e67bc0f148c2dd109f73a451e0a:/rand/grand.h

diff --git a/rand/grand.h b/rand/grand.h
new file mode 100644
index 0000000..ec11404
--- /dev/null
+++ b/rand/grand.h
@@ -0,0 +1,161 @@
+/* -*-c-*-
+ *
+ * Generic interface to random number generators
+ *
+ * (c) 1999 Straylight/Edgeware
+ */
+
+/*----- Licensing notice --------------------------------------------------*
+ *
+ * This file is part of Catacomb.
+ *
+ * Catacomb is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Library General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ *
+ * Catacomb is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with Catacomb; if not, write to the Free
+ * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
+ * MA 02111-1307, USA.
+ */
+
+#ifndef CATACOMB_GRAND_H
+#define CATACOMB_GRAND_H
+
+#ifdef __cplusplus
+  extern "C" {
+#endif
+
+/*----- Header files ------------------------------------------------------*/
+
+#include <assert.h>
+#include <stddef.h>
+
+#include <mLib/bits.h>
+
+/*----- Generic random number generator interface -------------------------*/
+
+typedef struct grand {
+  const struct grand_ops *ops;
+} grand;
+
+typedef struct grand_ops {
+
+  /* --- Various important properties --- */
+
+  const char *name;			/* Generator's name */
+  unsigned f;				/* Various flags */
+  uint32 max;				/* Maximum raw output */
+
+  /* --- Maintenance methods --- */
+
+  int (*misc)(grand */*r*/, unsigned /*op*/, ...); /* Miscellaneous ops */
+  void (*destroy)(grand */*r*/);	/* Destroy generator context */
+
+  /* --- Output methods --- *
+   *
+   * Only one of these operations need actually be implemented.  All the
+   * other operations may be synthesized.  Of course, performance is improved
+   * if more are provided.
+   */
+
+  uint32 (*raw)(grand */*r*/);		/* Uniform over %$[0, max)$% */
+  octet (*byte)(grand */*r*/);		/* Uniform over %$[0, 256)$% */
+  uint32 (*word)(grand */*r*/);		/* Uniform over %$[0, 2^{32})$% */
+  uint32 (*range)(grand */*r*/, uint32 /*l*/); /* Uniform over %$[0, l)$% */
+  void (*fill)(grand */*r*/, void */*p*/, size_t /*sz*/); /* Fill buffer */
+} grand_ops;
+
+#define GR_DESTROY(r)		(r)->ops->destroy((r))
+#define GR_RAW(r)		(r)->ops->raw((r))
+#define GR_WORD(r)		(r)->ops->word((r))
+#define GR_RANGE(r, l)		(r)->ops->range((r), (l))
+#define GR_FILL(r, p, sz)	(r)->ops->fill((r), (p), (sz))
+
+/* --- Flag types --- */
+
+#define GRAND_CRYPTO 1u			/* Cryptographically strong */
+
+/* --- Operation types --- */
+
+enum {
+
+  /* --- Required operations --- */
+
+  GRAND_CHECK,				/* @unsigned op2@ */
+
+  /* --- Standard seeding operations --- */
+
+  GRAND_SEEDINT,			/* @int i@ */
+  GRAND_SEEDUINT32,			/* @uint32 i@ */
+  GRAND_SEEDBLOCK,			/* @const void *p, size_t sz@ */
+  GRAND_SEEDMP,				/* @mp *m@ */
+  GRAND_SEEDRAND			/* @grand *g@ */
+
+  /* --- Generator-specific operations --- */
+
+#define GRAND_SPECIFIC(ch) ((unsigned)(ch) << 8)
+};
+
+#define GRAND_BADOP assert(((void)"bad grand_misc op", 0))
+
+/*----- Functions provided ------------------------------------------------*/
+
+/* --- @grand_byte@ --- *
+ *
+ * Arguments:	@grand *r@ = pointet to generic generator
+ *
+ * Returns:	A uniformly-distributed pseudorandom integer in the interval
+ *		%$[0, 256)$%.
+ */
+
+extern octet grand_byte(grand */*r*/);
+
+/* --- @grand_word@ --- *
+ *
+ * Arguments:	@grand *r@ = pointet to generic generator
+ *
+ * Returns:	A uniformly-distributed pseudorandom integer in the interval
+ *		%$[0, 2^{32})$%.
+ */
+
+extern uint32 grand_word(grand */*r*/);
+
+/* --- @grand_range@ --- *
+ *
+ * Arguments:	@grand *r@ = pointet to generic generator
+ *		@uint32 l@ = limit for acceptable results
+ *
+ * Returns:	A uniformly-distributed pseudorandom integer in the interval
+ *		%$[0, l)$%.
+ */
+
+extern uint32 grand_range(grand */*r*/, uint32 /*l*/);
+
+/* --- @grand_fill@ --- *
+ *
+ * Arguments:	@grand *r@ = pointet to generic generator
+ *		@void *p@ = pointer to a buffer
+ *		@size_t sz@ = size of the buffer
+ *
+ * Returns:	---
+ *
+ * Use:		Fills a buffer with uniformly distributed pseudorandom bytes
+ *		(see @grand_byte@).
+ */
+
+extern void grand_fill(grand */*r*/, void */*p*/, size_t /*sz*/);
+
+/*----- That's all, folks -------------------------------------------------*/
+
+#ifdef __cplusplus
+  }
+#endif
+
+#endif