package gnu.crypto.prng;
// ----------------------------------------------------------------------------
// $Id: IRandom.java,v 1.12 2005/10/06 04:24:17 rsdio Exp $
//
// Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc.
//
// This file is part of GNU Crypto.
//
// GNU Crypto is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2, or (at your option)
// any later version.
//
// GNU Crypto is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; see the file COPYING. If not, write to the
//
// Free Software Foundation Inc.,
// 51 Franklin Street, Fifth Floor,
// Boston, MA 02110-1301
// USA
//
// Linking this library statically or dynamically with other modules is
// making a combined work based on this library. Thus, the terms and
// conditions of the GNU General Public License cover the whole
// combination.
//
// As a special exception, the copyright holders of this library give
// you permission to link this library with independent modules to
// produce an executable, regardless of the license terms of these
// independent modules, and to copy and distribute the resulting
// executable under terms of your choice, provided that you also meet,
// for each linked independent module, the terms and conditions of the
// license of that module. An independent module is a module which is
// not derived from or based on this library. If you modify this
// library, you may extend this exception to your version of the
// library, but you are not obligated to do so. If you do not wish to
// do so, delete this exception statement from your version.
// ----------------------------------------------------------------------------
import java.util.Map;
/**
* <p>The basic visible methods of any pseudo-random number generator.</p>
*
* <p>The [HAC] defines a PRNG (as implemented in this library) as follows:</p>
*
* <ul>
* <li>"5.6 Definition: A pseudorandom bit generator (PRBG) is said to pass
* the <em>next-bit test</em> if there is no polynomial-time algorithm which,
* on input of the first <code>L</code> bits of an output sequence <code>S</code>,
* can predict the <code>(L+1)</code>st bit of <code>S</code> with a
* probability significantly grater than <code>1/2</code>."</li>
*
* <li>"5.8 Definition: A PRBG that passes the <em>next-bit test</em>
* (possibly under some plausible but unproved mathematical assumption such
* as the intractability of factoring integers) is called a
* <em>cryptographically secure pseudorandom bit generator</em> (CSPRBG)."</li>
* </ul>
*
* <p><b>IMPLEMENTATION NOTE</b>: Although all the concrete classes in this
* package implement the {@link Cloneable} interface, it is important to note
* here that such an operation, for those algorithms that use an underlting
* symmetric key block cipher, <b>DOES NOT</b> clone any session key material
* that may have been used in initialising the source PRNG (the instance to be
* cloned). Instead a clone of an already initialised PRNG, that uses and
* underlying symmetric key block cipher, is another instance with a clone of
* the same cipher that operates with the <b>same block size</b> but without any
* knowledge of neither key material nor key size.</p>
*
* <p>References:</p>
*
* <ol>
* <li><a href="http://www.cacr.math.uwaterloo.ca/hac">[HAC]</a>: Handbook of
* Applied Cryptography.<br>
* CRC Press, Inc. ISBN 0-8493-8523-7, 1997<br>
* Menezes, A., van Oorschot, P. and S. Vanstone.</li>
* </ol>
*
* @version $Revision: 1.12 $
*/
public interface IRandom extends Cloneable {
// Constants
// -------------------------------------------------------------------------
// Methods
// -------------------------------------------------------------------------
/**
* <p>Returns the canonical name of this instance.</p>
*
* @return the canonical name of this instance. */
String name();
/**
* <p>Initialises the pseudo-random number generator scheme with the
* appropriate attributes.</p>
*
* @param attributes a set of name-value pairs that describe the desired
* future instance behaviour.
* @exception IllegalArgumentException if at least one of the defined name/
* value pairs contains invalid data.
*/
void init(Map attributes);
/**
* <p>Returns the next 8 bits of random data generated from this instance.</p>
*
* @return the next 8 bits of random data generated from this instance.
* @exception IllegalStateException if the instance is not yet initialised.
* @exception LimitReachedException if this instance has reached its
* theoretical limit for generating non-repetitive pseudo-random data.
*/
byte nextByte() throws IllegalStateException, LimitReachedException;
/**
* <p>Fills the designated byte array, starting from byte at index
* <code>offset</code>, for a maximum of <code>length</code> bytes with the
* output of this generator instance.
*
* @param out the placeholder to contain the generated random bytes.
* @param offset the starting index in <i>out</i> to consider. This method
* does nothing if this parameter is not within <code>0</code> and
* <code>out.length</code>.
* @param length the maximum number of required random bytes. This method
* does nothing if this parameter is less than <code>1</code>.
* @exception IllegalStateException if the instance is not yet initialised.
* @exception LimitReachedException if this instance has reached its
* theoretical limit for generating non-repetitive pseudo-random data.
*/
void nextBytes(byte[] out, int offset, int length)
throws IllegalStateException, LimitReachedException;
/**
* <p>Supplement, or possibly replace, the random state of this PRNG with
* a random byte.</p>
*
* <p>Implementations are not required to implement this method in any
* meaningful way; this may be a no-operation, and implementations may
* throw an {@link UnsupportedOperationException}.</p>
*
* @param b The byte to add.
*/
void addRandomByte(byte b);
/**
* <p>Supplement, or possibly replace, the random state of this PRNG with
* a sequence of new random bytes.</p>
*
* <p>Implementations are not required to implement this method in any
* meaningful way; this may be a no-operation, and implementations may
* throw an {@link UnsupportedOperationException}.</p>
*
* @param in The buffer of new random bytes to add.
*/
void addRandomBytes(byte[] in);
/**
* <p>Supplement, or possibly replace, the random state of this PRNG with
* a sequence of new random bytes.</p>
*
* <p>Implementations are not required to implement this method in any
* meaningful way; this may be a no-operation, and implementations may
* throw an {@link UnsupportedOperationException}.</p>
*
* @param in The buffer of new random bytes to add.
* @param offset The offset from whence to begin reading random bytes.
* @param length The number of random bytes to add.
* @exception IndexOutOfBoundsException If <i>offset</i>, <i>length</i>,
* or <i>offset</i>+<i>length</i> is out of bounds.
*/
void addRandomBytes(byte[] in, int offset, int length);
/**
* <p>Returns a clone copy of this instance.</p>
*
* @return a clone copy of this instance.
*/
Object clone() throws CloneNotSupportedException;
}