gnu.crypto.prng.IRandom Maven / Gradle / Ivy
package gnu.crypto.prng;
// ----------------------------------------------------------------------------
// $Id: IRandom.java,v 1.8 2003/10/25 03:55:06 raif 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.,
// 59 Temple Place - Suite 330,
// Boston, MA 02111-1307
// 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;
/**
* The basic visible methods of any pseudo-random number generator.
*
* The [HAC] defines a PRNG (as implemented in this library) as follows:
*
*
* - "5.6 Definition: A pseudorandom bit generator (PRBG) is said to pass
* the next-bit test if there is no polynomial-time algorithm which,
* on input of the first
L bits of an output sequence S,
* can predict the (L+1)st bit of S with a
* probability significantly grater than 1/2."
*
* - "5.8 Definition: A PRBG that passes the next-bit test
* (possibly under some plausible but unproved mathematical assumption such
* as the intractability of factoring integers) is called a
* cryptographically secure pseudorandom bit generator (CSPRBG)."
*
*
* IMPLEMENTATION NOTE: 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, DOES NOT 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 same block size but without any
* knowledge of neither key material nor key size.
*
* References:
*
*
* - [HAC]: Handbook of
* Applied Cryptography.
* CRC Press, Inc. ISBN 0-8493-8523-7, 1997
* Menezes, A., van Oorschot, P. and S. Vanstone.
*
*
* @version $Revision: 1.8 $
*/
public interface IRandom extends Cloneable {
// Constants
// -------------------------------------------------------------------------
// Methods
// -------------------------------------------------------------------------
/**
* Returns the canonical name of this instance.
*
* @return the canonical name of this instance. */
String name();
/**
* Initialises the pseudo-random number generator scheme with the
* appropriate attributes.
*
* @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);
/**
* Returns the next 8 bits of random data generated from this instance.
*
* @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;
/**
* Fills the designated byte array, starting from byte at index
* offset, for a maximum of length bytes with the
* output of this generator instance.
*
* @param out the placeholder to contain the generated random bytes.
* @param offset the starting index in out to consider. This method
* does nothing if this parameter is not within 0 and
* out.length.
* @param length the maximum number of required random bytes. This method
* does nothing if this parameter is less than 1.
* @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;
/**
*
Returns a clone copy of this instance.
*
* @return a clone copy of this instance.
*/
Object clone();
}