/*
- silcrng.h
+ silcrng.h
Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1997 - 2002 Pekka Riikonen
+ Copyright (C) 1997 - 2003 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
*/
-/****h* silccrypt/SilcRNGAPI
+/****h* silccrypt/SILC RNG Interface
*
* DESCRIPTION
*
/****s* silccrypt/SilcRNGAPI/SilcRng
*
* NAME
- *
+ *
* typedef struct SilcRngStruct *SilcRng;
*
* DESCRIPTION
*
* SYNOPSIS
*
- * uint8 silc_rng_get_byte(SilcRng rng);
+ * SilcUInt8 silc_rng_get_byte(SilcRng rng);
*
* DESCRIPTION
*
* Returns one 8-bit random byte from the random number generator.
*
***/
-uint8 silc_rng_get_byte(SilcRng rng);
+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
*
- * uint16 silc_rng_get_rn16(SilcRng rng);
+ * SilcUInt16 silc_rng_get_rn16(SilcRng rng);
*
* DESCRIPTION
*
* Returns one 16-bit random number from the random number generator.
*
***/
-uint16 silc_rng_get_rn16(SilcRng rng);
+SilcUInt16 silc_rng_get_rn16(SilcRng rng);
/****f* silccrypt/SilcRNGAPI/silc_rng_get_rn32
*
* SYNOPSIS
*
- * uint32 silc_rng_get_rn32(SilcRng rng);
+ * SilcUInt32 silc_rng_get_rn32(SilcRng rng);
*
* DESCRIPTION
*
* Returns one 32-bit random number from the random number generator.
*
***/
-uint32 silc_rng_get_rn32(SilcRng rng);
+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, uint32 len);
+ * 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.
+ * 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, uint32 len);
+unsigned char *silc_rng_get_rn_string(SilcRng rng, SilcUInt32 len);
/****f* silccrypt/SilcRNGAPI/silc_rng_get_rn_data
*
* SYNOPSIS
*
- * unsigned char *silc_rng_get_rn_data(SilcRng rng, uint32 len);
+ * unsigned char *silc_rng_get_rn_data(SilcRng rng, SilcUInt32 len);
*
* DESCRIPTION
*
- * Returns random binary data of the length of `len' bytes. The
- * caller must free returned data buffer.
+ * Returns random binary data of the length of `len' bytes. The
+ * caller must free returned data buffer. It is guaranteed the data
+ * buffer does not include any zero (0x00) bytes.
*
***/
-unsigned char *silc_rng_get_rn_data(SilcRng rng, uint32 len);
+unsigned char *silc_rng_get_rn_data(SilcRng rng, SilcUInt32 len);
/****f* silccrypt/SilcRNGAPI/silc_rng_add_noise
*
* SYNOPSIS
*
- * void silc_rng_add_noise(SilcRng rng, unsigned char *buffer, uint32 len);
+ * 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
+ * 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, uint32 len);
+void silc_rng_add_noise(SilcRng rng, unsigned char *buffer, SilcUInt32 len);
/****f* silccrypt/SilcRNGAPI/silc_rng_global_init
*
*
* SYNOPSIS
*
- * uint8 silc_rng_global_get_byte(void);
+ * SilcUInt8 silc_rng_global_get_byte(void);
*
* DESCRIPTION
*
* Returns one 8-bit random byte from the random number generator.
*
***/
-uint8 silc_rng_global_get_byte(void);
+SilcUInt8 silc_rng_global_get_byte(void);
/****f* silccrypt/SilcRNGAPI/silc_rng_global_get_byte_fast
*
* SYNOPSIS
*
- * uint8 silc_rng_global_get_byte_fast(void);
+ * SilcUInt8 silc_rng_global_get_byte_fast(void);
*
* DESCRIPTION
*
* the byte from SILC RNG and is effectively same as silc_rng_get_byte.
*
***/
-uint8 silc_rng_global_get_byte_fast(void);
+SilcUInt8 silc_rng_global_get_byte_fast(void);
/****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn16
*
* SYNOPSIS
*
- * uint16 silc_rng_global_get_rn16(void);
+ * SilcUInt16 silc_rng_global_get_rn16(void);
*
* DESCRIPTION
*
* Returns one 16-bit random number from the random number generator.
*
***/
-uint16 silc_rng_global_get_rn16(void);
+SilcUInt16 silc_rng_global_get_rn16(void);
/****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn32
*
* SYNOPSIS
*
- * uint32 silc_rng_global_get_rn32(void);
+ * SilcUInt32 silc_rng_global_get_rn32(void);
*
* DESCRIPTION
*
* Returns one 32-bit random number from the random number generator.
*
***/
-uint32 silc_rng_global_get_rn32(void);
+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(uint32 len);
+ * 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.
+ * 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(uint32 len);
+unsigned char *silc_rng_global_get_rn_string(SilcUInt32 len);
/****f* silccrypt/SilcRNGAPI/silc_rng_global_get_rn_data
*
* SYNOPSIS
*
- * unsigned char *silc_rng_global_get_rn_data(uint32 len);
+ * unsigned char *silc_rng_global_get_rn_data(SilcUInt32 len);
*
* DESCRIPTION
*
- * Returns random binary data of the length of `len' bytes. The
- * caller must free returned data buffer.
+ * Returns random binary data of the length of `len' bytes. The
+ * caller must free returned data buffer. It is guaranteed the data
+ * buffer does not include any zero (0x00) bytes.
*
***/
-unsigned char *silc_rng_global_get_rn_data(uint32 len);
+unsigned char *silc_rng_global_get_rn_data(SilcUInt32 len);
/****f* silccrypt/SilcRNGAPI/silc_rng_global_add_noise
*
* SYNOPSIS
*
- * void silc_rng_global_add_noise(unsigned char *buffer, uint32 len);
+ * void silc_rng_global_add_noise(unsigned char *buffer, SilcUInt32 len);
*
* DESCRIPTION
*
- * Add the data buffer indicated by `buffer' of length of `len' bytes
+ * 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, uint32 len);
+void silc_rng_global_add_noise(unsigned char *buffer, SilcUInt32 len);
#endif