Random Number Generator

Module Implementation: OpenSSLCryptoInterfaceRNG

This module implements a self-seeding secure random number generator.

Note: Internal classes are italicized and will only contain a short description.

See the class-side examples in the OpenSSLRandomNumberGeneratorExamples class for additional usage detail.

RNG

OSSslRandom

OpenSSL Pseudo Random Number Generator.

Class methods: API

add: anObject entropy: aNumber

Mixes the num bytes at the string repr of anObject into the PRNG state. Entropy is an estimate of how much randomness is contained in anObject (measured in bytes.)

Answers:

<Number> entropy

 

cleanup

Securely erases the memory used by the PRNG.

 

loadRandomBytes: aFilename

On Unix platforms, besides Linux, OpenSSL's random number generator requires some entropy in order to be properly seeded.

Arguments:

aFilename - <String> the absolute path to a file containing psuedo-randomly generated bytes.

Answers:

<Integer> | <OpenSSLError compatible error>

 

loadRandomBytes: aFilename upTo: numberOfBytes

On Unix platforms, besides Linux, OpenSSL's random number generator requires some entropy in order to be properly seeded.

Arguments:

aFilename - <String> the absolute path to a file containing psuedo-randomly generated bytes.

Answers:

<Integer> | <OpenSSLError compatible error>

 

poll

Seeds the RNG using system-specific entropy sources (i.e. /dev/urandom on Unix and a combination of CryptGenRandom and other sources on Windows).

Note: While this is used to force a seed of the RNG using the system entropy sources, you should consider adding your own seed via #seed: or #add:entropy: if you feel you need this.

OpenSSL will auto-seed using this function internally when the RNG is initialized. Long-running server processes may wish reseed over some period of time but should not be called too often as this doesn't help increase entropy. If you believe you need to use this...refer to 'openssl discussion of Random_Numbers' first to understand exactly what this does.

Answers:

<Boolean> true if enough entropy available, false otherwise

 

randomBytes: numBytes

Answers numBytes worth of cryptographically strong pseudo-random bytes as a <ByteArray>. An error occurs if the PRNG has not been seeded with enough randomness to ensure an unpredictable byte sequence. OpenSSL will automatically seed when using this API.

Answers:

<ByteArray> - random bytes

 

randomBytes: numBytes into: bytebuffer

Fills @byteBuffer with @numBytes worth of cryptographically strong pseudo-random bytes.

An error occurs if the PRNG has not been seeded with enough randomness to ensure an unpredictable byte sequence.

Answers the @byteBuffer.

Answers:

<i.e. ByteArray | String | OSPtr> - random bytes

 

randomInt: aRange

Answers a cryptographically strong pseudo-random <OSSslBigNumber> in the range 0 <= rnd < aRange.

NOTE: aRange is EXCLUSIVE and this API answers an <OSSslBigNumber>.

If you require the <EsRandom> interface, then call the #nextInt: compatibility method which will answer an <Integer> and aRange is INCLUSIVE.

Answers:

<OSSslBigNumber> - random integer

 

seed: anObject

Mixes the num bytes at the string repr of anObject into the PRNG state.

Arguments:

anObject - <Object>

 

status

Answers true if the PRNG has been seeded with enough data, false otherwise. OpenSSL will automatically seed when using this API.

Answers:

<Boolean> true if sufficient

 

writeRandomBytes: aFilename

Writes a number of random bytes (currently 1024) to file named @aFilename which can be used to initialize the PRNG by calling #loadRandomBytes in a later session. Answer the number of bytes written, and an error object if the bytes written were generated without appropriate seed.

Arguments:

aFilename - <String> filename to write to.

Answers:

<Integer> the number of bytes written to the file

 

Class methods: Compatibility

nextInt: aRange

COMPATIBILITY METHOD: <EsRandom>. Answers a cryptographically strong pseudo-random <OSSslBigNumber> in the range 1 <= rnd <= aRange.

Arguments:

aRange - object that understands #asInteger, typically <Integer | OSSslBigNumber>

Answers:

<Integer> - random ranged integer

Raises:

<ExceptionalEvent> - compatible error mechanism