Class: RandomGenerator

• Inheritance
• Description
• Class protocol
  • adding entropy
  • change & update
  • initialization
  • instance creation
  • queries
• Instance protocol
  • basic reading
  • queries
  • reading
  • writing

Inheritance:

   Object
   |
   +--Stream
      |
      +--Random
         |
         +--RandomGenerator

Package:

stx:libbasic2

Category:

Magnitude-Numbers-Random

Version:

rev: 1.31 date: 2023/05/24 15:41:59

user: cg

file: RandomGenerator.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

Description:

This is a Random number generator, 
which uses either a OS random number generator or /dev/urandom,
or an ST/X internal random number generator.

WARNING: 
    this generator should NOT be used for cryptographic work 
UNLESS: 
    1) you are running on linux, solaris or osx,
    2) you have a working /dev/urandom.
    3) you can trust your /dev/urandom (I don't really know if any/all of them are good)

It is a facade one one of the other random generators,
and will choose (in decreasing priority) the first available generator from the following:

    - OS random system call 
    - /dev/urandom
    - rc4-based random (if present)
    - regular (untrusted) random as fallback
    


[instance variables:]

[class variables:]
    HasOSRandom     true if the operatingSystem supports random numbers
    RandFile        (if HasOSRandom is false and non-nil) the FileStream (/dev/random),
                    we get random numbers from

copyright
COPYRIGHT (c) 2007 by eXept Software AG
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

 addEntropy: entropyBytes

 update: something with: aParameter from: changedObject

handle image restarts and flush any device resource handles

 initialize

want to be informed when returning from snapshot

 openRandFile

try to open a random device

 new

return a new random number generator.
Try to get system random numbers from OS (e.g. in LINUX)
or device urandom (e.g. in Linux, OSX).
If no system random numbers are available, fall back to
a cryptographic secure PRNG (like RC4Random, part of the extra libcrypt package).
As last resort fallback to the cryptographic insecure linear builtin PRNG

Usage example(s):

each time, we do a new, add some entropy to the SharedRandomGenerator

 randPath

path to a file/device that is a source or random numbers

 randomDevicePathes

paths to look for OS sources of random numbers.
Can be configured at early startup to use something special
(i.e. a special hardware random device)
If never set, the defaults /dev/random, /dev/urandom are used

 randomDevicePathes: aCollectionOfPathesOrNil

configurable paths to look for OS sources of random numbers.
(can be set during early startup in an rc-file).
If never set, the defaults /dev/random, /dev/urandom are used

Instance protocol:

 nextByte

get the next random byte

Usage example(s):

RandomGenerator new nextByte

 nextBytes: cnt

get the next cnt random bytes

Usage example(s):

RandomGenerator new nextBytes:4

 maxInteger

return the max integral random number returned by nextInteger

Usage example(s):

RandomGenerator new maxInteger.

 next

return the next random number in the range 0..1

Usage example(s):

|r| r := RandomGenerator new. Transcript showCR:r next. Transcript showCR:r next. Transcript showCR:r next. Transcript showCR:r next.

 nextBoolean

return true or false by random

Usage example(s):

|r| r := RandomGenerator new. Transcript showCR:r nextBoolean. Transcript showCR:r nextBoolean. Transcript showCR:r nextBoolean. Transcript showCR:r nextBoolean.

Usage example(s):

Distribution should approach 50/50: |r bag| r := RandomGenerator new. bag := Bag new. 1000000 timesRepeat:[ bag add:(r nextBoolean). ]. Transcript showCR:bag contents

 nextCharacters: count

get the next count printable characters.
We answer printable characters in the ascii range (codepoints 32 - 126)

Usage example(s):

RandomGenerator new nextCharacters:8

 nextInteger

return the next integral random number,
in the range 0 .. 16r3FFFFFFF (32-bit)
or 0 .. 16r3FFFFFFFFFFFFFFF (64-bit).

Usage example(s):

|r| r := RandomGenerator new. Transcript showCR:r nextInteger. Transcript showCR:r nextInteger. Transcript showCR:r nextInteger. Transcript showCR:r nextInteger.

 nextLettersOrDigits: count

get the next count printable letters or digits [0-9A-Za-z].

Usage example(s):

RandomGenerator new nextLettersOrDigits:40

 nextPut: something

change the random pool by feeding in something.
Something should be some unpredictable, random event.
Ignored here

 nextPutAll: something

change the random pool by feeding in something.
Something should be some unpredictable, random event.
Ignored here