X-Git-Url: http://git.silcnet.org/gitweb/?a=blobdiff_plain;f=lib%2Fsilccrypt%2Fsilcrng.h;h=bf32fd8fcac2e9d9802613331b7559f03e86e49c;hb=e7b6c157b80152bf9fb9266e6bdd93f9fb0db776;hp=7dfc2d78982823b293eaa30589509bc8c5f45844;hpb=318d79b391bf6288e3e28c840217a7097f3d0392;p=silc.git diff --git a/lib/silccrypt/silcrng.h b/lib/silccrypt/silcrng.h index 7dfc2d78..bf32fd8f 100644 --- a/lib/silccrypt/silcrng.h +++ b/lib/silccrypt/silcrng.h @@ -1,16 +1,15 @@ /* - silcSilcRng.h + silcrng.h - Author: Pekka Riikonen + Author: Pekka Riikonen - Copyright (C) 1997 - 2000 Pekka Riikonen + Copyright (C) 1997 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - + the Free Software Foundation; version 2 of the License. + This program 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 @@ -18,35 +17,348 @@ */ +/****h* silccrypt/SILC RNG Interface + * + * DESCRIPTION + * + * SILC Random Number Generator is cryptographically strong pseudo random + * number generator. It is used to generate all the random numbers needed + * in the SILC sessions. All key material and other sources needing random + * numbers use this generator. + * + * The interface provides functions for retrieving different size of + * random number and arbitrary length of random data buffers. The interface + * also defines Global RNG API which makes it possible to call any + * RNG API function without specific RNG context. + * + ***/ + #ifndef SILCRNG_H #define SILCRNG_H -/* Forward declaration. Actual object is in source file. */ -typedef struct SilcRngObjectStruct *SilcRng; +/****s* silccrypt/SilcRNGAPI/SilcRng + * + * NAME + * + * typedef struct SilcRngStruct *SilcRng; + * + * DESCRIPTION + * + * This context is the actual Random Number Generator and is allocated + * by silc_rng_alloc and given as argument usually to all silc_rng_* + * functions. It is freed by the silc_rng_free function. The RNG is + * initialized by calling the silc_rng_init function. + * + ***/ +typedef struct SilcRngStruct *SilcRng; -/* Number of states to fetch data from pool. */ -#define SILC_RNG_STATE_NUM 4 +/* Prototypes */ -/* Byte size of the random data pool. */ -#define SILC_RNG_POOLSIZE 1024 +/****f* silccrypt/SilcRNGAPI/silc_rng_alloc + * + * SYNOPSIS + * + * SilcRng silc_rng_alloc(void); + * + * DESCRIPTION + * + * Allocates new SILC random number generator and returns context to + * it. After the RNG is allocated it must be initialized by calling + * silc_rng_init before it actually can be used to produce any random + * number. This function returns NULL if RNG could not allocated. + * + ***/ +SilcRng silc_rng_alloc(void); -/* Prototypes */ -SilcRng silc_rng_alloc(); +/****f* silccrypt/SilcRNGAPI/silc_rng_free + * + * SYNOPSIS + * + * void silc_rng_free(SilcRng rng); + * + * DESCRIPTION + * + * Frees the random number generator and destroys the random number + * pool. + * + ***/ void silc_rng_free(SilcRng rng); + +/****f* silccrypt/SilcRNGAPI/silc_rng_init + * + * SYNOPSIS + * + * void silc_rng_init(SilcRng rng); + * + * DESCRIPTION + * + * This function is used to initialize the random number generator. + * This is the function that must be called after the RNG is allocated + * by calling silc_rng_alloc. RNG cannot be used before this function + * is called. + * + * NOTES + * + * This function may be slow since it will acquire secret noise from + * the environment in an attempt to set the RNG in unguessable state. + * + ***/ void silc_rng_init(SilcRng rng); -void silc_rng_get_soft_noise(SilcRng rng); -void silc_rng_get_medium_noise(SilcRng rng); -void silc_rng_get_hard_noise(SilcRng rng); -void silc_rng_exec_command(SilcRng rng, char *command); -void silc_rng_add_noise(SilcRng rng, unsigned char *buffer, - unsigned int len); -void silc_rng_xor(SilcRng rng, unsigned int val, unsigned int pos); -void silc_rng_stir_pool(SilcRng rng); -unsigned int silc_rng_get_position(SilcRng rng); -unsigned char silc_rng_get_byte(SilcRng rng); -unsigned short silc_rng_get_rn16(SilcRng rng); -unsigned int silc_rng_get_rn32(SilcRng rng); -unsigned char *silc_rng_get_rn_string(SilcRng rng, unsigned int len); -unsigned char *silc_rng_get_rn_data(SilcRng rng, unsigned int len); + +/****f* silccrypt/SilcRNGAPI/silc_rng_get_byte + * + * SYNOPSIS + * + * SilcUInt8 silc_rng_get_byte(SilcRng rng); + * + * DESCRIPTION + * + * Returns one 8-bit random byte from the random number generator. + * + ***/ +SilcUInt8 silc_rng_get_byte(SilcRng rng); + +/****f* silccrypt/SilcRNGAPI/silc_rng_get_byte_fast + * + * SYNOPSIS + * + * SilcUInt8 silc_rng_get_byte_fast(SilcRng rng); + * + * DESCRIPTION + * + * Returns one 8-bit random byte from the random number generator as + * fast as possible. + * + * NOTES + * + * This will read the data from /dev/urandom if it is available in the + * operating system, since this may be faster than retrieving a byte + * from the SILC RNG. If /dev/urandom is not available this will take + * the byte from SILC RNG and is effectively same as silc_rng_get_byte. + * + ***/ +SilcUInt8 silc_rng_get_byte_fast(SilcRng rng); + +/****f* silccrypt/SilcRNGAPI/silc_rng_get_rn16 + * + * SYNOPSIS + * + * SilcUInt16 silc_rng_get_rn16(SilcRng rng); + * + * DESCRIPTION + * + * Returns one 16-bit random number from the random number generator. + * + ***/ +SilcUInt16 silc_rng_get_rn16(SilcRng rng); + +/****f* silccrypt/SilcRNGAPI/silc_rng_get_rn32 + * + * SYNOPSIS + * + * SilcUInt32 silc_rng_get_rn32(SilcRng rng); + * + * DESCRIPTION + * + * Returns one 32-bit random number from the random number generator. + * + ***/ +SilcUInt32 silc_rng_get_rn32(SilcRng rng); + +/****f* silccrypt/SilcRNGAPI/silc_rng_get_rn_string + * + * SYNOPSIS + * + * unsigned char *silc_rng_get_rn_string(SilcRng rng, SilcUInt32 len); + * + * DESCRIPTION + * + * Returns random string in HEX form of the length of `len' bytes. + * The caller must free returned data buffer. It is guaranteed the + * data string goes not include any zero (0x00) bytes. + * + ***/ +unsigned char *silc_rng_get_rn_string(SilcRng rng, SilcUInt32 len); + +/****f* silccrypt/SilcRNGAPI/silc_rng_get_rn_data + * + * SYNOPSIS + * + * SilcBool silc_rng_get_rn_data(SilcRng rng, SilcUInt32 len, + * unsigned char *buf, SilcUInt32 buf_size); + * + * DESCRIPTION + * + * Returns random binary data of the length of `len' bytes to the `buf' + * of maximum size of `buf_size'. It is guaranteed the data buffer does + * not include any zero (0x00) bytes. + * + ***/ +SilcBool silc_rng_get_rn_data(SilcRng rng, SilcUInt32 len, + unsigned char *buf, SilcUInt32 buf_size); + +/****f* silccrypt/SilcRNGAPI/silc_rng_add_noise + * + * SYNOPSIS + * + * void silc_rng_add_noise(SilcRng rng, unsigned char *buffer, SilcUInt32 len); + * + * DESCRIPTION + * + * Add the data buffer indicated by `buffer' of length of `len' bytes + * as noise to the random number generator. The random number generator + * is restirred (reseeded) when this function is called. + * + ***/ +void silc_rng_add_noise(SilcRng rng, unsigned char *buffer, SilcUInt32 len); + +/****f* silccrypt/SilcRNGAPI/silc_rng_global_init + * + * SYNOPSIS + * + * SilcBool silc_rng_global_init(SilcRng rng); + * + * DESCRIPTION + * + * This function sets the `rng' if non-NULL as global RNG context. + * When any of the silc_rng_global_* functions is called the `rng' is + * used as RNG. If `rng' is NULL this will allocate new RNG as global + * RNG. The application in this case must free it later by calling + * silc_rng_global_uninit. Returns TRUE after Global RNG is initialized. + * + * NOTES + * + * If `rng' was non-NULL, the silc_rng_init must have been called for + * the `rng' already. + * + * This function can be used to define the `rng' as global RNG and then + * use silc_rng_global_* functions easily without need to provide + * the RNG as argument. + * + ***/ +SilcBool silc_rng_global_init(SilcRng rng); + +/****f* silccrypt/SilcRNGAPI/silc_rng_global_uninit + * + * SYNOPSIS + * + * SilcBool silc_rng_global_uninit(void); + * + * DESCRIPTION + * + * Uninitialized the Global RNG object and frees it. This should not + * be called if silc_rng_global_init was called with non-NULL RNG. + * + ***/ +SilcBool silc_rng_global_uninit(void); + +/****f* silccrypt/SilcRNGAPI/silc_rng_global_get_byte + * + * SYNOPSIS + * + * SilcUInt8 silc_rng_global_get_byte(void); + * + * DESCRIPTION + * + * Returns one 8-bit random byte from the random number generator. + * + ***/ +SilcUInt8 silc_rng_global_get_byte(void); + +/****f* silccrypt/SilcRNGAPI/silc_rng_global_get_byte_fast + * + * SYNOPSIS + * + * SilcUInt8 silc_rng_global_get_byte_fast(void); + * + * DESCRIPTION + * + * Returns one 8-bit random byte from the random number generator as + * fast as possible. + * + * NOTES + * + * This will read the data from /dev/urandom if it is available in the + * operating system, since this may be faster than retrieving a byte + * from the SILC RNG. If /dev/urandom is not available this will take + * the byte from SILC RNG and is effectively same as silc_rng_get_byte. + * + ***/ +SilcUInt8 silc_rng_global_get_byte_fast(void); + +/****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn16 + * + * SYNOPSIS + * + * SilcUInt16 silc_rng_global_get_rn16(void); + * + * DESCRIPTION + * + * Returns one 16-bit random number from the random number generator. + * + ***/ +SilcUInt16 silc_rng_global_get_rn16(void); + +/****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn32 + * + * SYNOPSIS + * + * SilcUInt32 silc_rng_global_get_rn32(void); + * + * DESCRIPTION + * + * Returns one 32-bit random number from the random number generator. + * + ***/ +SilcUInt32 silc_rng_global_get_rn32(void); + +/****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn_string + * + * SYNOPSIS + * + * unsigned char *silc_rng_global_get_rn_string(SilcUInt32 len); + * + * DESCRIPTION + * + * Returns random string in HEX form of the length of `len' bytes. + * The caller must free returned data buffer. It is guaranteed the + * data string goes not include any zero (0x00) bytes. + * + ***/ +unsigned char *silc_rng_global_get_rn_string(SilcUInt32 len); + +/****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn_data + * + * SYNOPSIS + * + * SilcBool silc_rng_global_get_rn_data(SilcRng rng, SilcUInt32 len, + * unsigned char *buf, + * SilcUInt32 buf_size); + * + * DESCRIPTION + * + * Returns random binary data of the length of `len' bytes to the `buf' + * of maximum size of `buf_size'. It is guaranteed the data buffer does + * not include any zero (0x00) bytes. + * + ***/ +SilcBool silc_rng_global_get_rn_data(SilcRng rng, SilcUInt32 len, + unsigned char *buf, SilcUInt32 buf_size); + +/****f* silccrypt/SilcRNGAPI/silc_rng_global_add_noise + * + * SYNOPSIS + * + * void silc_rng_global_add_noise(unsigned char *buffer, SilcUInt32 len); + * + * DESCRIPTION + * + * Add the data buffer indicated by `buffer' of length of `len' bytes + * as noise to the random number generator. The random number generator + * is restirred (reseeded) when this function is called. + * + ***/ + +void silc_rng_global_add_noise(unsigned char *buffer, SilcUInt32 len); #endif