LibRGolf.c(November 2012)                            LibRGolf.c(November 2012)



NAME
       LibRGolf - A tiny library for generating high-quality random numbers

DESCRIPTION
       LibRGolf is a small (702-byte) library used for making
       cryptographically strong pseudo-random numbers. The random numbers
       generated by LibRGolf pass all of the "Die Hard" statistical tests for
       random numbers, and are believed to be a cryptographically strong
       bitstream of random numbers.

       The random number generator uses a string of any length, instead of a
       number, as a seed determining the random numbers generated. While the
       underlying random number generator (RNG) can use any binary string as
       the seed, the LibRGolf API only allows NULL-terminated C strings as RNG
       seeds.

       The underlying algorithm has a number of modes, including one for
       working with 32-bit integers, and another for 64-bit integers.
       LibRGolf uses the 32-bit version of the generator.

USAGE
       The library has two function calls: rgl() seeds and initializes the
       random number generator. It takes three arguments:

       * The first argument is what is called the "mill" of the random number
         generator. With LibRGolf, it is an array of 19 unsigned 32-bit
         integers (declared as uint32_t from <stdint.h>)

       * The second argument is the "belt" of the random number generator, and
         is an array of 40 unsigned 32-bit integers.

       * The third argument is a NULL-terminated string which is the seed for
         the random number generator.

       After being initalized with rgl(), rgi() uses the random number
       generator to generate a random 32-bit integer, taking the following
       arguments:

       * The first argument is what is called the "mill" of the random number
         generator. With LibRGolf, it is an array of 19 unsigned 32-bit
         integers (declared as uint32_t from <stdint.h>)

       * The second argument is the "belt" of the random number generator, and
         is an array of 40 unsigned 32-bit integers.

       * The third argument is the "phase" of the random number, and
         determines which byte we return from the RG32 state as a random
         number.  Its value starts off as 2, and alternates between 2 and 1.


EXAMPLE
       Here is a public domain example of the LibRGolf API being used:

       #include <stdint.h>
       #include <stdio.h>
       #include <stdlib.h>

       int main(int argc,char **argv){
               uint32_t belt[40], mill[19], phase = 2, c, j;

               if(argc < 2) {
                       printf("Usage: random_num '{random seed}'\n");
                       exit(1);
               }

               /* Seed random number generator */
               rgl(mill,belt,argv[1]);

               /* Generate 8 random numbers with PRNG */
               for(c = 0; c < 8; c++) {
                       j = rgi(mill, belt, &phase); /* Get number from PRNG */
                       printf("%d\n",j);
               }
               return 0;
       }


THE LIBRARY
       The library has been written in a manner to minimize its size. It is as
       follows, and has been donated to the public domain:

       #include <stdint.h> // Public domain random numbers
       #define rg uint32_t // NO WARRANTY
       #define rgp(a) for(c=0;c<a;c++)
       #define rgn w[c*13]^=s;u[16+c]^=s;
       void rgf(rg*a,rg*b){rg m=19,A[19],x,o=13,c,y,r=0;rgp(12)b[c+c%3*o]^=a
       [c+1];rgp(m){r=(c+r)&31;y=c*7;x=a[y++%m];x^=a[y%m]|~a[(y+1)%m];A[c]=x
       >>r|x<<(32-r);}for(y=39;y--;b[y+1]=b[y])a[y%m]=A[y%m]^A[(y+1)%m]^A[(y
       +4)%m];*a^=1;rgp(3)a[c+o]^=b[c*o]=b[c*o+o];}void rgl(rg*u,rg*w,char*v
       ){rg s,q,c,x;rgp(40)w[c]=u[c%19]=0;for(;;rgf(u,w)){rgp(3){for(s=q=0;q
       <4;){x=*v++;s|=(x?255&x:1)<<8*q++;if(!x){rgn;rgp(17)rgf(u,w);return;}
       }rgn;}}}rg rgi(rg*m,rg*b,rg*a){if(*a&2)rgf(m,b);return m[*a^=3];}

ABOUT THE ALGORITHM
       The algorithm used is the 32-bit version of a cryptographic primitive
       called RadioGatun. RadioGatun is the direct predecessor of SHA-3
       (Keccak) that the same team of world-renowned cryptographers developed.
       It is a secure pseudo-random number generator and probably a secure
       hash function for generating 512-bit hashes.

       RadioGatun's predecessor, Panama, has been around for over a decade
       and, while broken as a hash function, is still a secure stream cipher.
       While there have been some cryptographic analysis of RadioGatun, and
       while one of RadioGatun's designer admits that "experiments did not
       inspire confidence in RadioGatun", resulting in fairly significant
       tweaks between RadioGatun and SHA-3, there is at this time no attack,
       theoretical or otherwise, against unmodified 32-bit RadioGatun better
       than 2 ^ 352 (2 to the power of 352).

       Note that while the algorithm very quickly generates random numbers,
       there is a small delay initializing the random number generator: it
       uses roughly the computing resources necessary to create 32 random
       numbers to initalize the generator (more if the seed is a long string).



Golf code random number library    LIBRGOLF          LibRGolf.c(November 2012)