5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 2007 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silccrypt/SILC RNG Interface
24 * SILC Random Number Generator is cryptographically strong pseudo random
25 * number generator. It is used to generate all the random numbers needed
26 * in the SILC sessions. All key material and other sources needing random
27 * numbers use this generator.
29 * The interface provides functions for retrieving different size of
30 * random number and arbitrary length of random data buffers. The interface
31 * also defines Global RNG API which makes it possible to call any
32 * RNG API function without specific RNG context.
39 /****s* silccrypt/SilcRNGAPI/SilcRng
43 * typedef struct SilcRngStruct *SilcRng;
47 * This context is the actual Random Number Generator and is allocated
48 * by silc_rng_alloc and given as argument usually to all silc_rng_*
49 * functions. It is freed by the silc_rng_free function. The RNG is
50 * initialized by calling the silc_rng_init function.
53 typedef struct SilcRngStruct *SilcRng;
57 /****f* silccrypt/SilcRNGAPI/silc_rng_alloc
61 * SilcRng silc_rng_alloc(void);
65 * Allocates new SILC random number generator and returns context to
66 * it. After the RNG is allocated it must be initialized by calling
67 * silc_rng_init before it actually can be used to produce any random
68 * number. This function returns NULL if RNG could not allocated.
71 SilcRng silc_rng_alloc(void);
73 /****f* silccrypt/SilcRNGAPI/silc_rng_free
77 * void silc_rng_free(SilcRng rng);
81 * Frees the random number generator and destroys the random number
85 void silc_rng_free(SilcRng rng);
87 /****f* silccrypt/SilcRNGAPI/silc_rng_init
91 * void silc_rng_init(SilcRng rng);
95 * This function is used to initialize the random number generator.
96 * This is the function that must be called after the RNG is allocated
97 * by calling silc_rng_alloc. RNG cannot be used before this function
102 * This function may be slow since it will acquire secret noise from
103 * the environment in an attempt to set the RNG in unguessable state.
106 void silc_rng_init(SilcRng rng);
108 /****f* silccrypt/SilcRNGAPI/silc_rng_get_byte
112 * SilcUInt8 silc_rng_get_byte(SilcRng rng);
116 * Returns one 8-bit random byte from the random number generator.
119 SilcUInt8 silc_rng_get_byte(SilcRng rng);
121 /****f* silccrypt/SilcRNGAPI/silc_rng_get_byte_fast
125 * SilcUInt8 silc_rng_get_byte_fast(SilcRng rng);
129 * Returns one 8-bit random byte from the random number generator as
134 * This will read the data from /dev/urandom if it is available in the
135 * operating system, since this may be faster than retrieving a byte
136 * from the SILC RNG. If /dev/urandom is not available this will take
137 * the byte from SILC RNG and is effectively same as silc_rng_get_byte.
140 SilcUInt8 silc_rng_get_byte_fast(SilcRng rng);
142 /****f* silccrypt/SilcRNGAPI/silc_rng_get_rn16
146 * SilcUInt16 silc_rng_get_rn16(SilcRng rng);
150 * Returns one 16-bit random number from the random number generator.
153 SilcUInt16 silc_rng_get_rn16(SilcRng rng);
155 /****f* silccrypt/SilcRNGAPI/silc_rng_get_rn32
159 * SilcUInt32 silc_rng_get_rn32(SilcRng rng);
163 * Returns one 32-bit random number from the random number generator.
166 SilcUInt32 silc_rng_get_rn32(SilcRng rng);
168 /****f* silccrypt/SilcRNGAPI/silc_rng_get_rn_string
172 * unsigned char *silc_rng_get_rn_string(SilcRng rng, SilcUInt32 len);
176 * Returns random string in HEX form of the length of `len' bytes.
177 * The caller must free returned data buffer. It is guaranteed the
178 * data string goes not include any zero (0x00) bytes.
181 unsigned char *silc_rng_get_rn_string(SilcRng rng, SilcUInt32 len);
183 /****f* silccrypt/SilcRNGAPI/silc_rng_get_rn_data
187 * SilcBool silc_rng_get_rn_data(SilcRng rng, SilcUInt32 len,
188 * unsigned char *buf, SilcUInt32 buf_size);
192 * Returns random binary data of the length of `len' bytes to the `buf'
193 * of maximum size of `buf_size'. It is guaranteed the data buffer does
194 * not include any zero (0x00) bytes.
197 SilcBool silc_rng_get_rn_data(SilcRng rng, SilcUInt32 len,
198 unsigned char *buf, SilcUInt32 buf_size);
200 /****f* silccrypt/SilcRNGAPI/silc_rng_add_noise
204 * void silc_rng_add_noise(SilcRng rng, unsigned char *buffer, SilcUInt32 len);
208 * Add the data buffer indicated by `buffer' of length of `len' bytes
209 * as noise to the random number generator. The random number generator
210 * is restirred (reseeded) when this function is called.
213 void silc_rng_add_noise(SilcRng rng, unsigned char *buffer, SilcUInt32 len);
215 /****f* silccrypt/SilcRNGAPI/silc_rng_global_init
219 * SilcBool silc_rng_global_init(SilcRng rng);
223 * This function sets the `rng' if non-NULL as global RNG context.
224 * When any of the silc_rng_global_* functions is called the `rng' is
225 * used as RNG. If `rng' is NULL this will allocate new RNG as global
226 * RNG. The application in this case must free it later by calling
227 * silc_rng_global_uninit. Returns TRUE after Global RNG is initialized.
231 * If `rng' was non-NULL, the silc_rng_init must have been called for
234 * This function can be used to define the `rng' as global RNG and then
235 * use silc_rng_global_* functions easily without need to provide
236 * the RNG as argument.
239 SilcBool silc_rng_global_init(SilcRng rng);
241 /****f* silccrypt/SilcRNGAPI/silc_rng_global_uninit
245 * SilcBool silc_rng_global_uninit(void);
249 * Uninitialized the Global RNG object and frees it. This should not
250 * be called if silc_rng_global_init was called with non-NULL RNG.
253 SilcBool silc_rng_global_uninit(void);
255 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_byte
259 * SilcUInt8 silc_rng_global_get_byte(void);
263 * Returns one 8-bit random byte from the random number generator.
266 SilcUInt8 silc_rng_global_get_byte(void);
268 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_byte_fast
272 * SilcUInt8 silc_rng_global_get_byte_fast(void);
276 * Returns one 8-bit random byte from the random number generator as
281 * This will read the data from /dev/urandom if it is available in the
282 * operating system, since this may be faster than retrieving a byte
283 * from the SILC RNG. If /dev/urandom is not available this will take
284 * the byte from SILC RNG and is effectively same as silc_rng_get_byte.
287 SilcUInt8 silc_rng_global_get_byte_fast(void);
289 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn16
293 * SilcUInt16 silc_rng_global_get_rn16(void);
297 * Returns one 16-bit random number from the random number generator.
300 SilcUInt16 silc_rng_global_get_rn16(void);
302 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn32
306 * SilcUInt32 silc_rng_global_get_rn32(void);
310 * Returns one 32-bit random number from the random number generator.
313 SilcUInt32 silc_rng_global_get_rn32(void);
315 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn_string
319 * unsigned char *silc_rng_global_get_rn_string(SilcUInt32 len);
323 * Returns random string in HEX form of the length of `len' bytes.
324 * The caller must free returned data buffer. It is guaranteed the
325 * data string goes not include any zero (0x00) bytes.
328 unsigned char *silc_rng_global_get_rn_string(SilcUInt32 len);
330 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn_data
334 * SilcBool silc_rng_global_get_rn_data(SilcRng rng, SilcUInt32 len,
335 * unsigned char *buf,
336 * SilcUInt32 buf_size);
340 * Returns random binary data of the length of `len' bytes to the `buf'
341 * of maximum size of `buf_size'. It is guaranteed the data buffer does
342 * not include any zero (0x00) bytes.
345 SilcBool silc_rng_global_get_rn_data(SilcRng rng, SilcUInt32 len,
346 unsigned char *buf, SilcUInt32 buf_size);
348 /****f* silccrypt/SilcRNGAPI/silc_rng_global_add_noise
352 * void silc_rng_global_add_noise(unsigned char *buffer, SilcUInt32 len);
356 * Add the data buffer indicated by `buffer' of length of `len' bytes
357 * as noise to the random number generator. The random number generator
358 * is restirred (reseeded) when this function is called.
362 void silc_rng_global_add_noise(unsigned char *buffer, SilcUInt32 len);