Tim's ISAAC module.
[ccan] / ccan / isaac / _info.c
1 /**
2  * isaac - A fast, high-quality pseudo-random number generator.
3  *
4  * ISAAC (Indirect, Shift, Accumulate, Add, and Count) is the most advanced of
5  *  a series of pseudo-random number generators designed by Robert J. Jenkins
6  *  Jr. in 1996: http://www.burtleburtle.net/bob/rand/isaac.html
7  * To quote:
8  *   No efficient method is known for deducing their internal states.
9  *   ISAAC requires an amortized 18.75 instructions to produce a 32-bit value.
10  *   There are no cycles in ISAAC shorter than 2**40 values.
11  *   The expected cycle length is 2**8295 values.
12  *   ...
13  *   ISAAC-64 generates a different sequence than ISAAC, but it uses the same
14  *    principles.
15  *   It uses 64-bit arithmetic.
16  *   It generates a 64-bit result every 19 instructions.
17  *   All cycles are at least 2**72 values, and the average cycle length is
18  *    2**16583.
19  * An additional, important comment from Bob Jenkins in 2006:
20  *   Seeding a random number generator is essentially the same problem as
21  *    encrypting the seed with a block cipher.
22  *   ISAAC should be initialized with the encryption of the seed by some
23  *    secure cipher.
24  *   I've provided a seeding routine in my implementations, which nobody has
25  *    broken so far, but I have less faith in that initialization routine than
26  *    I have in ISAAC.
27  *
28  * A number of attacks on ISAAC have been published.
29  * [Pudo01] can recover the entire internal state and has expected running time
30  *  less than the square root of the number of states, or 2**4121 (4.67E+1240).
31  * [Auma06] reveals a large set of weak states, consisting of those for which
32  *  the first value is repeated one or more times elsewhere in the state
33  *  vector.
34  * These induce a bias in the output relative to the repeated value.
35  * The seed values used as input below are scrambled before being used, so any
36  *  duplicates in them do not imply duplicates in the resulting internal state,
37  *  however the chances of some duplicate existing elsewhere in a random state
38  *  are just over 255/2**32, or merely 1 in 16 million.
39  * Such states are, of course, much rarer in ISAAC-64.
40  * It is not clear if an attacker can tell from just the output if ISAAC is in
41  *  a weak state, or deduce the full internal state in any case except that
42  *  where all or almost all of the entries in the state vector are identical.
43  *   @MISC{Pudo01,
44  *     author="Marina Pudovkina",
45  *     title="A Known Plaintext Attack on the {ISAAC} Keystream Generator",
46  *     howpublished="Cryptology ePrint Archive, Report 2001/049",
47  *     year=2001,
48  *     note="\url{http://eprint.iacr.org/2001/049}",
49  *   }
50  *   @MISC{Auma06,
51  *     author="Jean-Philippe Aumasson",
52  *     title="On the Pseudo-Random Generator {ISAAC}",
53  *     howpublished="Cryptology ePrint Archive, Report 2006/438",
54  *     year=2006,
55  *     note="\url{http://eprint.iacr.org/2006/438}",
56  *   }
57  *
58  * Even if one does not trust the security of this PRNG (and, without a good
59  *  source of entropy to seed it, one should not), ISAAC is an excellent source
60  *  of high-quality random numbers for Monte Carlo simulations, etc.
61  * It is the fastest 32-bit generator among all of those that pass the
62  *  statistical tests in the recent survey
63  *  http://www.iro.umontreal.ca/~simardr/testu01/tu01.html, with the exception
64  *  of Marsa-LFIB4, and it is quite competitive on 64-bit archtectures.
65  * Unlike Marsa-LFIB4 (and all other LFib generators), there are no linear
66  *  dependencies between successive values, and unlike many generators found in
67  *  libc implementations, there are no small periods in the least significant
68  *  bits, or seeds which lead to very small periods in general.
69  *
70  * Example:
71  *  #include <stdio.h>
72  *  #include <time.h>
73  *  #include <ccan/isaac/isaac.h>
74  *
75  *  int main(void){
76  *    static const char *CHEESE[3]={"Cheddar","Provolone","Camembert"};
77  *    isaac_ctx     isaac;
78  *    unsigned char seed[8];
79  *    time_t        now;
80  *    int           i;
81  *    //N.B.: time() is not a good source of entropy.
82  *    //Do not use it for cryptogrpahic purposes.
83  *    time(&now);
84  *    //Print it out so we can reproduce problems if needed.
85  *    printf("Seed: 0x%016llX\n",(long long)now);
86  *    //And convert the time to a byte array so that we can reproduce the same
87  *    // seed on platforms with different endianesses.
88  *    for(i=0;i<8;i++){
89  *      seed[i]=(unsigned char)(now&0xFF);
90  *      now>>=8;
91  *    }
92  *    isaac_init(&isaac,seed,8);
93  *    printf("0x%08lX\n",(long)isaac_next_uint32(&isaac));
94  *    printf("%s\n",CHEESE[isaac_next_uint(&isaac,3)]);
95  *    printf("%0.8G\n",isaac_next_float(&isaac));
96  *    printf("%0.8G\n",isaac_next_signed_float(&isaac));
97  *    printf("%0.18G\n",isaac_next_double(&isaac));
98  *    printf("%0.18G\n",isaac_next_signed_double(&isaac));
99  *    return 0;
100  *  }
101  *
102  * License: Public Domain
103  */
104 #include <string.h>
105 #include "config.h"
106
107 int main(int _argc,const char *_argv[]){
108   /*Expect exactly one argument.*/
109   if(_argc!=2)return 1;
110   if(strcmp(_argv[1],"depends")==0){
111     /*PRINTF-CCAN-PACKAGES-YOU-NEED-ONE-PER-LINE-IF-ANY*/
112     printf("ccan/ilog\n");
113     return 0;
114   }
115   return 1;
116 }