.\" Process this file with the following
.\" nroff -man -Tutf8 maradns.8 | tr '\020' ' '
.\"
.\" Last updated San Jul 22 2017
.\"
.TH LibRGolf.c "November 2012" LIBRGOLF "Golf code random number library"
.\" We don't want hyphenation (it's too ugly)
.\" We also disable justification when using nroff
.\" Due to the way the -mandoc macro works, this needs to be placed
.\" after the .TH heading
.hy 0
.if n .na
.\"
.\" We need the following stuff so that we can have single quotes
.\" In both groff and other UNIX *roff processors
.if \n(.g .mso www.tmac
.ds aq \(aq
.if !\n(.g .if '\(aq'' .ds aq \'
.SH "NAME"
.PP
LibRGolf - A tiny library for generating high-quality random numbers
.SH "DESCRIPTION"
.PP
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.
.PP
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.
.PP
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.
.SH "USAGE"
.PP
The library has two function calls: rgl() seeds and initializes the
random number generator. It takes three arguments:
.TP 2
*
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 )
.TP 2
*
The second argument is the "belt" of the random number generator, and
is an array of 40 unsigned 32-bit integers.
.TP 2
*
The third argument is a NULL-terminated string which is the seed for
the random number generator.
.PP
After being initalized with rgl(), rgi() uses the random number generator
to generate a random 32-bit integer, taking the following arguments:
.TP 2
*
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 )
.TP 2
*
The second argument is the "belt" of the random number generator, and
is an array of 40 unsigned 32-bit integers.
.TP 2
*
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.
.PP
.SH "EXAMPLE"
.PP
Here is a public domain example of the LibRGolf API being used:
.nf
#include
#include
#include
int main(int argc,char **argv){
uint32_t belt[40], mill[19], phase = 2, c, j;
if(argc < 2) {
printf("Usage: random_num \(aq{random seed}\(aq\\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;
}
.fi
.SH "THE LIBRARY"
.PP
The library has been written in a manner to minimize its size. It is
as follows, and has been donated to the public domain:
.nf
#include // Public domain random numbers
#define rg uint32_t // NO WARRANTY
#define rgp(a) for(c=0;c>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];}
.fi
.SH "ABOUT THE ALGORITHM"
.PP
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.
.PP
RadioGatun\(aqs 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\(aqs 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).
.PP
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).