3 * Generic interface to random number generators
5 * (c) 1999 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of Catacomb.
12 * Catacomb is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Library General Public License as
14 * published by the Free Software Foundation; either version 2 of the
15 * License, or (at your option) any later version.
17 * Catacomb is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Library General Public License for more details.
22 * You should have received a copy of the GNU Library General Public
23 * License along with Catacomb; if not, write to the Free
24 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
28 #ifndef CATACOMB_GRAND_H
29 #define CATACOMB_GRAND_H
35 /*----- Header files ------------------------------------------------------*/
40 #include <mLib/bits.h>
42 /*----- Generic random number generator interface -------------------------*/
44 typedef struct grand {
45 const struct grand_ops *ops;
48 typedef struct grand_ops {
50 /* --- Various important properties --- */
52 const char *name; /* Generator's name */
53 unsigned f; /* Various flags */
54 uint32 max; /* Maximum raw output, if nonzero;
55 * must be either zero or at least
59 /* --- Maintenance methods --- */
61 int (*misc)(grand */*r*/, unsigned /*op*/, ...); /* Miscellaneous ops */
62 void (*destroy)(grand */*r*/); /* Destroy generator context */
64 /* --- Output methods --- *
66 * Of these, only @raw@ need be implemented directly by the generator: the
67 * others can point to provided @grand_default...@ functions, which will
68 * synthesize the necessary behaviour. Of course, this comes at an
72 uint32 (*raw)(grand */*r*/); /* Uniform over %$[0, max)$% */
73 octet (*byte)(grand */*r*/); /* Uniform over %$[0, 256)$% */
74 uint32 (*word)(grand */*r*/); /* Uniform over %$[0, 2^{32})$% */
75 uint32 (*range)(grand */*r*/, uint32 /*l*/); /* Uniform over %$[0, l)$% */
76 void (*fill)(grand */*r*/, void */*p*/, size_t /*sz*/); /* Fill buffer */
79 #define GR_DESTROY(r) (r)->ops->destroy((r))
80 #define GR_RAW(r) (r)->ops->raw((r))
81 #define GR_WORD(r) (r)->ops->word((r))
82 #define GR_RANGE(r, l) (r)->ops->range((r), (l))
83 #define GR_FILL(r, p, sz) (r)->ops->fill((r), (p), (sz))
85 /* --- Flag types --- */
87 #define GRAND_CRYPTO 1u /* Cryptographically strong */
89 /* --- Operation types --- */
93 /* --- Required operations --- */
95 GRAND_CHECK, /* @unsigned op2@ */
97 /* --- Standard seeding operations --- */
99 GRAND_SEEDINT, /* @int i@ */
100 GRAND_SEEDUINT32, /* @uint32 i@ */
101 GRAND_SEEDBLOCK, /* @const void *p, size_t sz@ */
102 GRAND_SEEDMP, /* @mp *m@ */
103 GRAND_SEEDRAND /* @grand *g@ */
105 /* --- Generator-specific operations --- */
107 #define GRAND_SPECIFIC(ch) ((unsigned)(ch) << 8)
110 #define GRAND_BADOP assert(((void)"bad grand_misc op", 0))
112 /*----- Default operations ------------------------------------------------*/
114 /* --- @grand_defaultbyte@ --- *
116 * Arguments: @grand *r@ = pointet to generic generator
118 * Returns: A uniformly-distributed pseudorandom integer in the interval
121 * Use: Default @byte@ output method. This calls the @range@ method
122 * to return a uniform random value between 0 and 255.
125 extern octet grand_defaultbyte(grand */*r*/);
127 /* --- @grand_defaultword@ --- *
129 * Arguments: @grand *r@ = pointet to generic generator
131 * Returns: A uniformly-distributed pseudorandom integer in the interval
134 * Use: Default @word@ output method. This calls the @fill@ method
135 * to fill a 4-octet buffer with uniform random bytes, and then
136 * converts them to an integer.
139 extern uint32 grand_defaultword(grand */*r*/);
141 /* --- @grand_defaultrange@ --- *
143 * Arguments: @grand *r@ = pointet to generic generator
144 * @uint32 l@ = limit for acceptable results
146 * Returns: A uniformly-distributed pseudorandom integer in the interval
149 * Use: Default @range@ output method. This falls back to either
150 * @word@ (if the generator's @max@ is zero, or if @max < l@) or
151 * @raw@ (otherwise). This might recurse via @fill@ and @byte@,
152 * but this is safe because of the constraint on the @raw@
156 extern uint32 grand_defaultrange(grand */*r*/, uint32 /*l*/);
158 /* --- @grand_defaultfill@ --- *
160 * Arguments: @grand *r@ = pointet to generic generator
161 * @void *p@ = pointer to a buffer
162 * @size_t sz@ = size of the buffer
166 * Use: Fills a buffer with uniformly distributed pseudorandom bytes.
167 * This calls the @byte@ method repeatedly to fill in the output
171 extern void grand_defaultfill(grand */*r*/, void */*p*/, size_t /*sz*/);
173 /*----- Functions provided ------------------------------------------------*/
175 /* --- @grand_byte@ --- *
177 * Arguments: @grand *r@ = pointet to generic generator
179 * Returns: A uniformly-distributed pseudorandom integer in the interval
183 extern octet grand_byte(grand */*r*/);
185 /* --- @grand_word@ --- *
187 * Arguments: @grand *r@ = pointet to generic generator
189 * Returns: A uniformly-distributed pseudorandom integer in the interval
193 extern uint32 grand_word(grand */*r*/);
195 /* --- @grand_range@ --- *
197 * Arguments: @grand *r@ = pointet to generic generator
198 * @uint32 l@ = limit for acceptable results
200 * Returns: A uniformly-distributed pseudorandom integer in the interval
204 extern uint32 grand_range(grand */*r*/, uint32 /*l*/);
206 /* --- @grand_fill@ --- *
208 * Arguments: @grand *r@ = pointet to generic generator
209 * @void *p@ = pointer to a buffer
210 * @size_t sz@ = size of the buffer
214 * Use: Fills a buffer with uniformly distributed pseudorandom bytes
215 * (see @grand_byte@).
218 extern void grand_fill(grand */*r*/, void */*p*/, size_t /*sz*/);
220 /*----- That's all, folks -------------------------------------------------*/