1 /* 2 3 silcrng.h 4 5 Author: Pekka Riikonen <priikone@silcnet.org> 6 7 Copyright (C) 1997 - 2003 Pekka Riikonen 8 9 The contents of this file are subject to one of the Licenses specified 10 in the COPYING file; You may not use this file except in compliance 11 with the License. 12 13 The software distributed under the License is distributed on an "AS IS" 14 basis, in the hope that it will be useful, but WITHOUT WARRANTY OF ANY 15 KIND, either expressed or implied. See the COPYING file for more 16 information. 17 18 */ 19 20 /****h* silccrypt/SILC RNG Interface 21 * 22 * DESCRIPTION 23 * 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. 28 * 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. 33 * 34 ***/ 35 36 #ifndef SILCRNG_H 37 #define SILCRNG_H 38 39 /****s* silccrypt/SilcRNGAPI/SilcRng 40 * 41 * NAME 42 * 43 * typedef struct SilcRngStruct *SilcRng; 44 * 45 * DESCRIPTION 46 * 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. 51 * 52 ***/ 53 typedef struct SilcRngStruct *SilcRng; 54 55 /* Prototypes */ 56 57 /****f* silccrypt/SilcRNGAPI/silc_rng_alloc 58 * 59 * SYNOPSIS 60 * 61 * SilcRng silc_rng_alloc(void); 62 * 63 * DESCRIPTION 64 * 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. 69 * 70 ***/ 71 SilcRng silc_rng_alloc(void); 72 73 /****f* silccrypt/SilcRNGAPI/silc_rng_free 74 * 75 * SYNOPSIS 76 * 77 * void silc_rng_free(SilcRng rng); 78 * 79 * DESCRIPTION 80 * 81 * Frees the random number generator and destroys the random number 82 * pool. 83 * 84 ***/ 85 void silc_rng_free(SilcRng rng); 86 87 /****f* silccrypt/SilcRNGAPI/silc_rng_init 88 * 89 * SYNOPSIS 90 * 91 * void silc_rng_init(SilcRng rng); 92 * 93 * DESCRIPTION 94 * 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 98 * is called. 99 * 100 * NOTES 101 * 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. 104 * 105 ***/ 106 void silc_rng_init(SilcRng rng); 107 108 /****f* silccrypt/SilcRNGAPI/silc_rng_get_byte 109 * 110 * SYNOPSIS 111 * 112 * SilcUInt8 silc_rng_get_byte(SilcRng rng); 113 * 114 * DESCRIPTION 115 * 116 * Returns one 8-bit random byte from the random number generator. 117 * 118 ***/ 119 SilcUInt8 silc_rng_get_byte(SilcRng rng); 120 121 /****f* silccrypt/SilcRNGAPI/silc_rng_get_byte_fast 122 * 123 * SYNOPSIS 124 * 125 * SilcUInt8 silc_rng_get_byte_fast(SilcRng rng); 126 * 127 * DESCRIPTION 128 * 129 * Returns one 8-bit random byte from the random number generator as 130 * fast as possible. 131 * 132 * NOTES 133 * 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. 138 * 139 ***/ 140 SilcUInt8 silc_rng_get_byte_fast(SilcRng rng); 141 142 /****f* silccrypt/SilcRNGAPI/silc_rng_get_rn16 143 * 144 * SYNOPSIS 145 * 146 * SilcUInt16 silc_rng_get_rn16(SilcRng rng); 147 * 148 * DESCRIPTION 149 * 150 * Returns one 16-bit random number from the random number generator. 151 * 152 ***/ 153 SilcUInt16 silc_rng_get_rn16(SilcRng rng); 154 155 /****f* silccrypt/SilcRNGAPI/silc_rng_get_rn32 156 * 157 * SYNOPSIS 158 * 159 * SilcUInt32 silc_rng_get_rn32(SilcRng rng); 160 * 161 * DESCRIPTION 162 * 163 * Returns one 32-bit random number from the random number generator. 164 * 165 ***/ 166 SilcUInt32 silc_rng_get_rn32(SilcRng rng); 167 168 /****f* silccrypt/SilcRNGAPI/silc_rng_get_rn_string 169 * 170 * SYNOPSIS 171 * 172 * unsigned char *silc_rng_get_rn_string(SilcRng rng, SilcUInt32 len); 173 * 174 * DESCRIPTION 175 * 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. 179 * 180 ***/ 181 unsigned char *silc_rng_get_rn_string(SilcRng rng, SilcUInt32 len); 182 183 /****f* silccrypt/SilcRNGAPI/silc_rng_get_rn_data 184 * 185 * SYNOPSIS 186 * 187 * unsigned char *silc_rng_get_rn_data(SilcRng rng, SilcUInt32 len); 188 * 189 * DESCRIPTION 190 * 191 * Returns random binary data of the length of `len' bytes. The 192 * caller must free returned data buffer. It is guaranteed the data 193 * buffer does not include any zero (0x00) bytes. 194 * 195 ***/ 196 unsigned char *silc_rng_get_rn_data(SilcRng rng, SilcUInt32 len); 197 198 /****f* silccrypt/SilcRNGAPI/silc_rng_add_noise 199 * 200 * SYNOPSIS 201 * 202 * void silc_rng_add_noise(SilcRng rng, unsigned char *buffer, SilcUInt32 len); 203 * 204 * DESCRIPTION 205 * 206 * Add the data buffer indicated by `buffer' of length of `len' bytes 207 * as noise to the random number generator. The random number generator 208 * is restirred (reseeded) when this function is called. 209 * 210 ***/ 211 void silc_rng_add_noise(SilcRng rng, unsigned char *buffer, SilcUInt32 len); 212 213 /****f* silccrypt/SilcRNGAPI/silc_rng_global_init 214 * 215 * SYNOPSIS 216 * 217 * SilcBool silc_rng_global_init(SilcRng rng); 218 * 219 * DESCRIPTION 220 * 221 * This function sets the `rng' if non-NULL as global RNG context. 222 * When any of the silc_rng_global_* functions is called the `rng' is 223 * used as RNG. If `rng' is NULL this will allocate new RNG as global 224 * RNG. The application in this case must free it later by calling 225 * silc_rng_global_uninit. Returns TRUE after Global RNG is initialized. 226 * 227 * NOTES 228 * 229 * If `rng' was non-NULL, the silc_rng_init must have been called for 230 * the `rng' already. 231 * 232 * This function can be used to define the `rng' as global RNG and then 233 * use silc_rng_global_* functions easily without need to provide 234 * the RNG as argument. 235 * 236 ***/ 237 SilcBool silc_rng_global_init(SilcRng rng); 238 239 /****f* silccrypt/SilcRNGAPI/silc_rng_global_uninit 240 * 241 * SYNOPSIS 242 * 243 * SilcBool silc_rng_global_uninit(void); 244 * 245 * DESCRIPTION 246 * 247 * Uninitialized the Global RNG object and frees it. This should not 248 * be called if silc_rng_global_init was called with non-NULL RNG. 249 * 250 ***/ 251 SilcBool silc_rng_global_uninit(void); 252 253 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_byte 254 * 255 * SYNOPSIS 256 * 257 * SilcUInt8 silc_rng_global_get_byte(void); 258 * 259 * DESCRIPTION 260 * 261 * Returns one 8-bit random byte from the random number generator. 262 * 263 ***/ 264 SilcUInt8 silc_rng_global_get_byte(void); 265 266 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_byte_fast 267 * 268 * SYNOPSIS 269 * 270 * SilcUInt8 silc_rng_global_get_byte_fast(void); 271 * 272 * DESCRIPTION 273 * 274 * Returns one 8-bit random byte from the random number generator as 275 * fast as possible. 276 * 277 * NOTES 278 * 279 * This will read the data from /dev/urandom if it is available in the 280 * operating system, since this may be faster than retrieving a byte 281 * from the SILC RNG. If /dev/urandom is not available this will take 282 * the byte from SILC RNG and is effectively same as silc_rng_get_byte. 283 * 284 ***/ 285 SilcUInt8 silc_rng_global_get_byte_fast(void); 286 287 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn16 288 * 289 * SYNOPSIS 290 * 291 * SilcUInt16 silc_rng_global_get_rn16(void); 292 * 293 * DESCRIPTION 294 * 295 * Returns one 16-bit random number from the random number generator. 296 * 297 ***/ 298 SilcUInt16 silc_rng_global_get_rn16(void); 299 300 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn32 301 * 302 * SYNOPSIS 303 * 304 * SilcUInt32 silc_rng_global_get_rn32(void); 305 * 306 * DESCRIPTION 307 * 308 * Returns one 32-bit random number from the random number generator. 309 * 310 ***/ 311 SilcUInt32 silc_rng_global_get_rn32(void); 312 313 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn_string 314 * 315 * SYNOPSIS 316 * 317 * unsigned char *silc_rng_global_get_rn_string(SilcUInt32 len); 318 * 319 * DESCRIPTION 320 * 321 * Returns random string in HEX form of the length of `len' bytes. 322 * The caller must free returned data buffer. It is guaranteed the 323 * data string goes not include any zero (0x00) bytes. 324 * 325 ***/ 326 unsigned char *silc_rng_global_get_rn_string(SilcUInt32 len); 327 328 /****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn_data 329 * 330 * SYNOPSIS 331 * 332 * unsigned char *silc_rng_global_get_rn_data(SilcUInt32 len); 333 * 334 * DESCRIPTION 335 * 336 * Returns random binary data of the length of `len' bytes. The 337 * caller must free returned data buffer. It is guaranteed the data 338 * buffer does not include any zero (0x00) bytes. 339 * 340 ***/ 341 unsigned char *silc_rng_global_get_rn_data(SilcUInt32 len); 342 343 /****f* silccrypt/SilcRNGAPI/silc_rng_global_add_noise 344 * 345 * SYNOPSIS 346 * 347 * void silc_rng_global_add_noise(unsigned char *buffer, SilcUInt32 len); 348 * 349 * DESCRIPTION 350 * 351 * Add the data buffer indicated by `buffer' of length of `len' bytes 352 * as noise to the random number generator. The random number generator 353 * is restirred (reseeded) when this function is called. 354 * 355 ***/ 356 357 void silc_rng_global_add_noise(unsigned char *buffer, SilcUInt32 len); 358 359 #endif 360