Package org.random.rjgodoy.trng

This library provides a SecureRandom service, integrated with the Java Security API, for accessing RANDOM.ORG (a web-service that generates true random numbers from atmospheric noise).

See:
Description

Class Summary

MH_HttpClient	Mini HTTP-Client for accessing www.random.org.
MH_PoolDaemon	Provides information and configuration of the pool daemon.
MH_SecureRandom	A SecureRandom implementation accessing www.random.org.
MH_SecureRandomSpi	SecureRandomSpi implementation that uses the True Random Number generator from www.random.org.
RjgodoyProvider	java.security.Provider implementating client for TRNG www.random.org from Mads Haahr and random.irb.hr at Ruder Boskovic Institute This provider defines the SecureRandom service MH_TRNG.

Enum Summary

FallbackPolicy	Values for the org.random.rjgodoy.trng.fallback property.
GeneratorMode	Values for the org.random.rjgodoy.trng.mode property.

Package org.random.rjgodoy.trng Description

This library provides a SecureRandom service, integrated with the Java Security API, for accessing RANDOM.ORG (a web-service that generates true random numbers from atmospheric noise).

A sample application demonstrating the usage of this library is provided in the source file TRNG.java.

Initialization

Some system properties may be set before requesting the first SecureRandom instance. Class MH_SecureRandom provides static fields with the names of each property.

The only required property is USER, which configures the client to supply an email address in the User-Agent field of the request, as required by random.org terms of service.

In order to set this property you should do either System.setProperty("org.random.rjgodoy.trng.user", "user@example.org"); or System.setProperty(MH_SecureRandom.USER,"user@example.org"); Note you may also set this property by passing a -D parameter to the Java application launcher. (The latter form is required if the provider is configured in the java.security file)

There are other properties for enabling features such as SSL/TLS and an auxiliar PRNG, which may be used either as a backup source of pseudo-randomness (for avoiding blocking when the quota is exceeded) or for operating in mixed mode (i.e. TRNG xor PRNG) in case you are too paranoid to trust third party randomness.

Instantiating the generator

Method A:

1. Create an instance of MH_SecureRandom, which extends SecureRandom.
2. In the code, explictly instantiate the generator as SecureRandom srandom = new MH_SecureRandom();

Method B (preferred):

Register the provider and request an implemenation of the "MH_TRNG algorithm, which access www.random.org. (Note: This method may fail if the code is executing without privileges for inserting a new provider.)
Security.addProvider(new RjgodoyProvider());
SecureRandom srandom = SecureRandom.getInstance("MH_TRNG");

Method C:

1.Edit the JRE_HOME/lib/security/java.security file and configure the provider.
2.In the code, instantiate the generator by doing SecureRandom srandom = SecureRandom.getInstance("MH_TRNG");

Usage

Once you have instantiated the generator, as described above, you may use it as a normal Random instance. Indeed: it extends class Random, but the values are generated from atmosferic noise instead of using a linear congruential PRNG.

If you haven't already, you may want to look at www.random.org in order to know more about this service.

Logging

Logging will use the Apache Commons Logging library, if available. If this library is not in the classpath, then a version of org.apache.commons.logging.impl.SimpleLog (already included) will be used. Four log modules are defined by this library.

MH_SecureRandomSpi

the SecureRandom engine .

MH_HttpClient

the HTTP client connecting to random.org

MH_Daemon

the pool daemon.

RjgodoyProvider

the Provider which registers MH_SecureRandomSpi with the Java API.

If the default logger is used, the detail level for each modules may be configured by setting a system property "org.apache.commons.logging.simplelog.log.xxxxxx" (where xxxxxx is the module name) with one of the following values: "trace", "debug", "info", "warn", "error", or "fatal".