Commit | Line | Data |
---|---|---|
aa1082f2 | 1 | /* -*-c-*- |
aa1082f2 | 2 | * |
3 | * Generic interface to random number generators | |
4 | * | |
5 | * (c) 1999 Straylight/Edgeware | |
6 | */ | |
7 | ||
45c0fd36 | 8 | /*----- Licensing notice --------------------------------------------------* |
aa1082f2 | 9 | * |
10 | * This file is part of Catacomb. | |
11 | * | |
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. | |
45c0fd36 | 16 | * |
aa1082f2 | 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. | |
45c0fd36 | 21 | * |
aa1082f2 | 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, | |
25 | * MA 02111-1307, USA. | |
26 | */ | |
27 | ||
aa1082f2 | 28 | #ifndef CATACOMB_GRAND_H |
29 | #define CATACOMB_GRAND_H | |
30 | ||
31 | #ifdef __cplusplus | |
32 | extern "C" { | |
33 | #endif | |
34 | ||
35 | /*----- Header files ------------------------------------------------------*/ | |
36 | ||
37 | #include <assert.h> | |
38 | #include <stddef.h> | |
39 | ||
40 | #include <mLib/bits.h> | |
41 | ||
42 | /*----- Generic random number generator interface -------------------------*/ | |
43 | ||
44 | typedef struct grand { | |
45 | const struct grand_ops *ops; | |
46 | } grand; | |
47 | ||
48 | typedef struct grand_ops { | |
49 | ||
50 | /* --- Various important properties --- */ | |
51 | ||
52 | const char *name; /* Generator's name */ | |
159bb2d9 | 53 | unsigned f; /* Various flags */ |
44ff6c11 MW |
54 | uint32 max; /* Maximum raw output, if nonzero; |
55 | * must be either zero or at least | |
56 | * 256 | |
57 | */ | |
aa1082f2 | 58 | |
59 | /* --- Maintenance methods --- */ | |
60 | ||
61 | int (*misc)(grand */*r*/, unsigned /*op*/, ...); /* Miscellaneous ops */ | |
62 | void (*destroy)(grand */*r*/); /* Destroy generator context */ | |
63 | ||
64 | /* --- Output methods --- * | |
65 | * | |
44ff6c11 MW |
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 | |
69 | * efficiency penalty. | |
aa1082f2 | 70 | */ |
71 | ||
72 | uint32 (*raw)(grand */*r*/); /* Uniform over %$[0, max)$% */ | |
159bb2d9 | 73 | octet (*byte)(grand */*r*/); /* Uniform over %$[0, 256)$% */ |
aa1082f2 | 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 */ | |
77 | } grand_ops; | |
78 | ||
b817bfc6 | 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)) | |
84 | ||
159bb2d9 | 85 | /* --- Flag types --- */ |
86 | ||
76ba9c8f | 87 | #define GRAND_CRYPTO 1u /* Cryptographically strong */ |
159bb2d9 | 88 | |
aa1082f2 | 89 | /* --- Operation types --- */ |
90 | ||
91 | enum { | |
92 | ||
93 | /* --- Required operations --- */ | |
94 | ||
95 | GRAND_CHECK, /* @unsigned op2@ */ | |
96 | ||
97 | /* --- Standard seeding operations --- */ | |
98 | ||
99 | GRAND_SEEDINT, /* @int i@ */ | |
100 | GRAND_SEEDUINT32, /* @uint32 i@ */ | |
101 | GRAND_SEEDBLOCK, /* @const void *p, size_t sz@ */ | |
102 | GRAND_SEEDMP, /* @mp *m@ */ | |
1709c9a1 | 103 | GRAND_SEEDRAND /* @grand *g@ */ |
aa1082f2 | 104 | |
105 | /* --- Generator-specific operations --- */ | |
106 | ||
45c0fd36 | 107 | #define GRAND_SPECIFIC(ch) ((unsigned)(ch) << 8) |
aa1082f2 | 108 | }; |
109 | ||
110 | #define GRAND_BADOP assert(((void)"bad grand_misc op", 0)) | |
111 | ||
44ff6c11 MW |
112 | /*----- Default operations ------------------------------------------------*/ |
113 | ||
114 | /* --- @grand_defaultbyte@ --- * | |
115 | * | |
116 | * Arguments: @grand *r@ = pointet to generic generator | |
117 | * | |
118 | * Returns: A uniformly-distributed pseudorandom integer in the interval | |
119 | * %$[0, 256)$%. | |
120 | * | |
121 | * Use: Default @byte@ output method. This calls the @range@ method | |
122 | * to return a uniform random value between 0 and 255. | |
123 | */ | |
124 | ||
125 | extern octet grand_defaultbyte(grand */*r*/); | |
126 | ||
127 | /* --- @grand_defaultword@ --- * | |
128 | * | |
129 | * Arguments: @grand *r@ = pointet to generic generator | |
130 | * | |
131 | * Returns: A uniformly-distributed pseudorandom integer in the interval | |
132 | * %$[0, 2^{32})$%. | |
133 | * | |
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. | |
137 | */ | |
138 | ||
139 | extern uint32 grand_defaultword(grand */*r*/); | |
140 | ||
141 | /* --- @grand_defaultrange@ --- * | |
142 | * | |
143 | * Arguments: @grand *r@ = pointet to generic generator | |
144 | * @uint32 l@ = limit for acceptable results | |
145 | * | |
146 | * Returns: A uniformly-distributed pseudorandom integer in the interval | |
147 | * %$[0, l)$%. | |
148 | * | |
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@ | |
153 | * method. | |
154 | */ | |
155 | ||
156 | extern uint32 grand_defaultrange(grand */*r*/, uint32 /*l*/); | |
157 | ||
158 | /* --- @grand_defaultfill@ --- * | |
159 | * | |
160 | * Arguments: @grand *r@ = pointet to generic generator | |
161 | * @void *p@ = pointer to a buffer | |
162 | * @size_t sz@ = size of the buffer | |
163 | * | |
164 | * Returns: --- | |
165 | * | |
166 | * Use: Fills a buffer with uniformly distributed pseudorandom bytes. | |
167 | * This calls the @byte@ method repeatedly to fill in the output | |
168 | * buffer. | |
169 | */ | |
170 | ||
171 | extern void grand_defaultfill(grand */*r*/, void */*p*/, size_t /*sz*/); | |
172 | ||
aa1082f2 | 173 | /*----- Functions provided ------------------------------------------------*/ |
174 | ||
175 | /* --- @grand_byte@ --- * | |
176 | * | |
177 | * Arguments: @grand *r@ = pointet to generic generator | |
178 | * | |
179 | * Returns: A uniformly-distributed pseudorandom integer in the interval | |
180 | * %$[0, 256)$%. | |
181 | */ | |
182 | ||
183 | extern octet grand_byte(grand */*r*/); | |
184 | ||
185 | /* --- @grand_word@ --- * | |
186 | * | |
187 | * Arguments: @grand *r@ = pointet to generic generator | |
188 | * | |
189 | * Returns: A uniformly-distributed pseudorandom integer in the interval | |
190 | * %$[0, 2^{32})$%. | |
191 | */ | |
192 | ||
193 | extern uint32 grand_word(grand */*r*/); | |
194 | ||
195 | /* --- @grand_range@ --- * | |
196 | * | |
197 | * Arguments: @grand *r@ = pointet to generic generator | |
198 | * @uint32 l@ = limit for acceptable results | |
199 | * | |
200 | * Returns: A uniformly-distributed pseudorandom integer in the interval | |
201 | * %$[0, l)$%. | |
202 | */ | |
203 | ||
204 | extern uint32 grand_range(grand */*r*/, uint32 /*l*/); | |
205 | ||
206 | /* --- @grand_fill@ --- * | |
207 | * | |
208 | * Arguments: @grand *r@ = pointet to generic generator | |
209 | * @void *p@ = pointer to a buffer | |
210 | * @size_t sz@ = size of the buffer | |
211 | * | |
212 | * Returns: --- | |
213 | * | |
214 | * Use: Fills a buffer with uniformly distributed pseudorandom bytes | |
215 | * (see @grand_byte@). | |
216 | */ | |
217 | ||
218 | extern void grand_fill(grand */*r*/, void */*p*/, size_t /*sz*/); | |
219 | ||
220 | /*----- That's all, folks -------------------------------------------------*/ | |
221 | ||
222 | #ifdef __cplusplus | |
223 | } | |
224 | #endif | |
225 | ||
226 | #endif |