randm.h

00001 /*****************************************************************************
00002 * randm.h - Random number generator header file.
00003 *
00004 * Copyright (c) 2003 by Marc Boucher, Services Informatiques (MBSI) inc.
00005 * Copyright (c) 1998 Global Election Systems Inc.
00006 *
00007 * The authors hereby grant permission to use, copy, modify, distribute,
00008 * and license this software and its documentation for any purpose, provided
00009 * that existing copyright notices are retained in all copies and that this
00010 * notice and the following disclaimer are included verbatim in any 
00011 * distributions. No written agreement, license, or royalty fee is required
00012 * for any of the authorized uses.
00013 *
00014 * THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS *AS IS* AND ANY EXPRESS OR
00015 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
00016 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
00017 * IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00018 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
00019 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
00020 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
00021 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00022 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
00023 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00024 *
00025 ******************************************************************************
00026 * REVISION HISTORY
00027 *
00028 * 03-01-01 Marc Boucher <marc@mbsi.ca>
00029 *   Ported to lwIP.
00030 * 98-05-29 Guy Lancaster <glanca@gesn.com>, Global Election Systems Inc.
00031 *   Extracted from avos.
00032 *****************************************************************************/
00033 
00034 #ifndef RANDM_H
00035 #define RANDM_H
00036 
00037 /***********************
00038 *** PUBLIC FUNCTIONS ***
00039 ***********************/
00040 /*
00041  * Initialize the random number generator.
00042  */
00043 void avRandomInit(void);
00044 
00045 /*
00046  * Churn the randomness pool on a random event.  Call this early and often
00047  * on random and semi-random system events to build randomness in time for
00048  * usage.  For randomly timed events, pass a null pointer and a zero length
00049  * and this will use the system timer and other sources to add randomness.
00050  * If new random data is available, pass a pointer to that and it will be
00051  * included.
00052  */
00053 void avChurnRand(char *randData, u32_t randLen);
00054 
00055 /*
00056  * Randomize our random seed value.  To be called for truely random events
00057  * such as user operations and network traffic.
00058  */
00059 #if MD5_SUPPORT
00060 #define avRandomize() avChurnRand(NULL, 0)
00061 #else  /* MD5_SUPPORT */
00062 void avRandomize(void);
00063 #endif /* MD5_SUPPORT */
00064 
00065 /*
00066  * Use the random pool to generate random data.  This degrades to pseudo
00067  * random when used faster than randomness is supplied using churnRand().
00068  * Thus it's important to make sure that the results of this are not
00069  * published directly because one could predict the next result to at
00070  * least some degree.  Also, it's important to get a good seed before
00071  * the first use.
00072  */
00073 void avGenRand(char *buf, u32_t bufLen);
00074 
00075 /*
00076  * Return a new random number.
00077  */
00078 u32_t avRandom(void);
00079 
00080 
00081 #endif /* RANDM_H */